@axiosleo/orm-mysql 0.14.4 → 0.15.0

package/README.md

@@ -477,6 +477,49 @@ const hanlder = new QueryHandler(conn, {
 });
 ```
 
+## AI Skills
+
+This project ships with AI Skills that teach AI coding assistants how to use this library correctly. You can install them with a single command:
+
+```bash
+# Cursor
+npx @axiosleo/orm-mysql skills --install=cursor
+
+# Claude Code
+npx @axiosleo/orm-mysql skills --install=claude
+
+# Windsurf
+npx @axiosleo/orm-mysql skills --install=windsurf
+```
+
+The command detects the locally installed version of `@axiosleo/orm-mysql` in your `node_modules/` and copies the matching skill files. If the package is not installed locally, it will use the bundled skills and remind you to run `npm install @axiosleo/orm-mysql`.
+
+To uninstall:
+
+```bash
+npx @axiosleo/orm-mysql skills --uninstall=cursor
+npx @axiosleo/orm-mysql skills --uninstall=claude
+npx @axiosleo/orm-mysql skills --uninstall=windsurf
+```
+
+### Skill Files
+
+| File | Content |
+|------|---------|
+| `SKILL.md` | Setup, class hierarchy, quick start |
+| `query-building.md` | table, attr, join, orderBy, limit, groupBy |
+| `where-conditions.md` | where, whereIn, whereLike, whereBetween |
+| `crud-operations.md` | select, find, insert, update, delete, incrBy |
+| `transactions.md` | beginTransaction, isolation levels, row locking |
+
+### Manual Installation
+
+For other AI tools, copy the skill files from `node_modules/@axiosleo/orm-mysql/skills/` into your tool's custom instructions directory:
+
+```bash
+cp -r node_modules/@axiosleo/orm-mysql/skills/ .your-tool/skills/orm-mysql-usage/
+```
+
 ## License
 
 This project is open-sourced software licensed under [MIT](LICENSE).

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.14.4',
+  version: '0.15.0',
   commands_dir: path.join(__dirname, '../commands'),
 });
 

package/commands/skills.js

@@ -0,0 +1,223 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { Command, printer } = require('@axiosleo/cli-tool');
+const { _exists, _copy, _read, _read_json, _mkdir } = require('@axiosleo/cli-tool/src/helper/fs');
+
+const SKILL_FILES = [
+  'SKILL.md',
+  'query-building.md',
+  'where-conditions.md',
+  'crud-operations.md',
+  'transactions.md',
+];
+
+const SUPPORTED_TARGETS = ['cursor', 'claude', 'windsurf'];
+
+const PKG_NAME = '@axiosleo/orm-mysql';
+
+function getTargetDir(cwd, target) {
+  const map = {
+    cursor: path.join(cwd, '.cursor', 'skills', 'orm-mysql-usage'),
+    windsurf: path.join(cwd, '.windsurf', 'skills', 'orm-mysql-usage'),
+  };
+  return map[target] || null;
+}
+
+async function resolveSkillsSource(cwd) {
+  const localPkgJson = path.join(cwd, 'node_modules', PKG_NAME, 'package.json');
+  let localPkgFound = false;
+  let localVersion = null;
+
+  if (await _exists(localPkgJson)) {
+    localPkgFound = true;
+    const pkg = await _read_json(localPkgJson);
+    localVersion = pkg.version;
+    const skillsDir = path.join(cwd, 'node_modules', PKG_NAME, 'skills');
+    if (await _exists(skillsDir)) {
+      return { dir: skillsDir, version: localVersion, local: true, outdated: false };
+    }
+  }
+
+  const fallbackDir = path.join(__dirname, '..', 'skills');
+  if (await _exists(fallbackDir)) {
+    const fallbackPkg = path.join(__dirname, '..', 'package.json');
+    let version = 'unknown';
+    if (await _exists(fallbackPkg)) {
+      const pkg = await _read_json(fallbackPkg);
+      version = pkg.version;
+    }
+    return {
+      dir: fallbackDir,
+      version,
+      local: false,
+      outdated: localPkgFound,
+      localVersion,
+    };
+  }
+  return null;
+}
+
+class SkillsCommand extends Command {
+  constructor() {
+    super({
+      name: 'skills',
+      desc: 'Install or uninstall AI skills for coding assistants (Cursor, Claude Code, Windsurf)',
+    });
+    this.addOption('install', 'i', 'Install skills for target tool (cursor, claude, windsurf)', 'optional', '');
+    this.addOption('uninstall', 'u', 'Uninstall skills for target tool (cursor, claude, windsurf)', 'optional', '');
+  }
+
+  async exec(args, options) {
+    const install = options.install;
+    const uninstall = options.uninstall;
+
+    if (!install && !uninstall) {
+      this.printUsage();
+      return;
+    }
+
+    if (install) {
+      await this.install(install);
+    } else if (uninstall) {
+      await this.uninstall(uninstall);
+    }
+  }
+
+  printUsage() {
+    printer.println();
+    printer.println('Usage:');
+    printer.println('  orm-mysql skills --install=<target>     Install AI skills');
+    printer.println('  orm-mysql skills --uninstall=<target>   Uninstall AI skills');
+    printer.println();
+    printer.println('Supported targets: ' + SUPPORTED_TARGETS.join(', '));
+    printer.println();
+    printer.println('Examples:');
+    printer.println('  npx @axiosleo/orm-mysql skills --install=cursor');
+    printer.println('  npx @axiosleo/orm-mysql skills --install=claude');
+    printer.println('  npx @axiosleo/orm-mysql skills --uninstall=cursor');
+    printer.println();
+  }
+
+  async install(target) {
+    if (!SUPPORTED_TARGETS.includes(target)) {
+      printer.error(`Unsupported target: "${target}". Supported targets: ${SUPPORTED_TARGETS.join(', ')}`);
+      return;
+    }
+
+    const cwd = process.cwd();
+    const source = await resolveSkillsSource(cwd);
+
+    if (!source) {
+      printer.error('Could not find skills files. Please reinstall @axiosleo/orm-mysql.');
+      return;
+    }
+
+    if (source.local) {
+      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(`  npm install ${PKG_NAME}@latest`);
+      printer.println();
+      printer.info(`Using skills from npx ${PKG_NAME}@${source.version} instead.`);
+    } else {
+      printer.warning(`${PKG_NAME} is not installed locally in this project.`);
+      printer.warning(`Consider running: npm install ${PKG_NAME}`);
+      printer.println();
+    }
+
+    printer.info(`Installing skills for ${target} from ${PKG_NAME}@${source.version}...`);
+
+    if (target === 'claude') {
+      await this.installClaude(cwd, source);
+    } else {
+      await this.installCopyTarget(cwd, target, source);
+    }
+  }
+
+  async installCopyTarget(cwd, target, source) {
+    const targetDir = getTargetDir(cwd, target);
+    await _mkdir(targetDir);
+    await _copy(source.dir, targetDir, true);
+    printer.success(`Skills installed to ${path.relative(cwd, targetDir)}/`);
+    printer.println();
+    printer.println('Files installed:');
+    for (const file of SKILL_FILES) {
+      printer.println(`  - ${file}`);
+    }
+    printer.println();
+  }
+
+  async installClaude(cwd, source) {
+    const claudeFile = path.join(cwd, 'CLAUDE.md');
+    const header = `<!-- ${PKG_NAME}@${source.version} skills -->\n`;
+    const separator = '\n---\n\n';
+
+    let content = header;
+    for (const file of SKILL_FILES) {
+      const filePath = path.join(source.dir, file);
+      if (await _exists(filePath)) {
+        const fileContent = await _read(filePath);
+        content += separator + fileContent.trim() + '\n';
+      }
+    }
+
+    if (await _exists(claudeFile)) {
+      const existing = await _read(claudeFile);
+      if (existing.includes(`<!-- ${PKG_NAME}`) && existing.includes('skills -->')) {
+        printer.warning('CLAUDE.md already contains @axiosleo/orm-mysql skills.');
+        printer.warning('Please remove the existing skills section first, or run:');
+        printer.warning('  npx @axiosleo/orm-mysql skills --uninstall=claude');
+        return;
+      }
+    }
+
+    fs.appendFileSync(claudeFile, '\n' + content);
+    printer.success(`Skills appended to ${path.relative(cwd, claudeFile)}`);
+    printer.println();
+  }
+
+  async uninstall(target) {
+    if (!SUPPORTED_TARGETS.includes(target)) {
+      printer.error(`Unsupported target: "${target}". Supported targets: ${SUPPORTED_TARGETS.join(', ')}`);
+      return;
+    }
+
+    const cwd = process.cwd();
+
+    if (target === 'claude') {
+      this.uninstallClaude(cwd);
+      return;
+    }
+
+    const targetDir = getTargetDir(cwd, target);
+    if (await _exists(targetDir)) {
+      fs.rmSync(targetDir, { recursive: true, force: true });
+      printer.success(`Skills removed from ${path.relative(cwd, targetDir)}/`);
+    } else {
+      printer.warning(`No skills found at ${path.relative(cwd, targetDir)}/`);
+    }
+  }
+
+  uninstallClaude(cwd) {
+    const claudeFile = path.join(cwd, 'CLAUDE.md');
+    if (!fs.existsSync(claudeFile)) {
+      printer.warning('CLAUDE.md not found.');
+      return;
+    }
+    const content = fs.readFileSync(claudeFile, 'utf8');
+    const startMarker = `<!-- ${PKG_NAME}`;
+    const idx = content.indexOf(startMarker);
+    if (idx === -1) {
+      printer.warning('No @axiosleo/orm-mysql skills section found in CLAUDE.md.');
+      return;
+    }
+    const cleaned = content.substring(0, idx).trimEnd() + '\n';
+    fs.writeFileSync(claudeFile, cleaned);
+    printer.success('Skills section removed from CLAUDE.md');
+  }
+}
+
+module.exports = SkillsCommand;

package/package.json

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

package/skills/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: orm-mysql-usage
+description: Build MySQL queries, perform CRUD operations, and manage transactions using @axiosleo/orm-mysql. Use when writing database queries, building where conditions, inserting/updating/deleting rows, managing transactions, or working with the ORM query builder in this project.
+---
+
+# @axiosleo/orm-mysql Usage Guide
+
+## Installation
+
+```bash
+npm install @axiosleo/orm-mysql
+```
+
+## Setup
+
+### Create a Connection
+
+```javascript
+const { createClient, QueryHandler } = require("@axiosleo/orm-mysql");
+
+const conn = createClient({
+  host: "localhost",
+  port: 3306,
+  user: "root",
+  password: "password",
+  database: "my_db",
+});
+
+const db = new QueryHandler(conn);
+```
+
+### Create a Connection Pool (recommended for production)
+
+```javascript
+const { createPool, QueryHandler } = require("@axiosleo/orm-mysql");
+
+const pool = createPool({
+  host: "localhost",
+  port: 3306,
+  user: "root",
+  password: "password",
+  database: "my_db",
+  connectionLimit: 10,
+});
+
+const db = new QueryHandler(pool);
+```
+
+### Using MySQLClient
+
+```javascript
+const { MySQLClient } = require("@axiosleo/orm-mysql");
+
+const client = new MySQLClient({
+  host: "localhost",
+  port: 3306,
+  user: "root",
+  password: "password",
+  database: "my_db",
+}, null, "pool"); // "default" | "promise" | "pool"
+
+const rows = await client.table("users").select();
+await client.close();
+```
+
+## Class Hierarchy
+
+```
+QueryCondition      -- where clauses (where, whereIn, whereLike, whereBetween...)
+  └── Query         -- query building (table, attr, join, orderBy, limit, page...)
+        └── QueryOperator          -- execution (select, find, insert, update, delete...)
+              └── TransactionOperator  -- adds append() for row locking
+```
+
+- `QueryHandler` wraps a connection/pool and creates `QueryOperator` via `.table(name)`
+- `TransactionHandler` wraps a promise connection and creates `TransactionOperator` via `.table(name)`
+
+## Quick Start
+
+```javascript
+const db = new QueryHandler(conn);
+
+// SELECT
+const users = await db.table("users")
+  .where("age", ">", 18)
+  .orderBy("name", "asc")
+  .limit(10)
+  .select("id", "name", "age");
+
+// INSERT
+await db.table("users").insert({ name: "Joe", age: 25 });
+
+// UPDATE
+await db.table("users").where("id", 1).update({ age: 26 });
+
+// DELETE
+await db.table("users").where("id", 1).delete();
+
+// COUNT
+const total = await db.table("users").where("age", ">", 18).count();
+
+// FIND single row
+const user = await db.table("users").where("id", 1).find();
+```
+
+## Dry Run with notExec()
+
+Call `notExec()` before any CRUD method to get a `Builder` object with `.sql` and `.values` instead of executing:
+
+```javascript
+const builder = await db.table("users")
+  .where("age", ">", 18)
+  .notExec()
+  .select("id", "name");
+
+console.log(builder.sql);    // "SELECT `id`, `name` FROM `users` WHERE `age` > ?"
+console.log(builder.values); // [18]
+```
+
+## Reference Files
+
+| Scenario | File |
+|----------|------|
+| 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) |
+| Transactions (beginTransaction, commit, rollback, FOR UPDATE) | [transactions.md](transactions.md) |
+
+## Hooks
+
+Register pre/post hooks for query operations:
+
+```javascript
+const { Hook } = require("@axiosleo/orm-mysql");
+
+Hook.pre(async (options) => {
+  console.log("Before:", options.operator, options.tables);
+}, { table: "users", opt: "insert" });
+
+Hook.post(async (options, result) => {
+  console.log("After:", result);
+}, { table: "users", opt: "insert" });
+```
+
+## Schema Helpers
+
+```javascript
+const exists = await db.existTable("users");
+const dbExists = await db.existDatabase("my_db");
+const fields = await db.getTableFields("my_db", "users", "COLUMN_NAME", "DATA_TYPE");
+```
+
+## Raw SQL
+
+```javascript
+const result = await db.query({ sql: "SELECT * FROM users WHERE id = ?", values: [1] });
+```

package/skills/crud-operations.md

@@ -0,0 +1,223 @@
+# CRUD Operations
+
+The `QueryOperator` class provides all execution methods. You get an instance via `db.table("name")`.
+
+All CRUD methods return a `Promise`. Write operations resolve to `MySQLQueryResult` (OkPacket | ResultSetHeader). If `notExec()` was called, they resolve to a `Builder` object instead.
+
+## Read Operations
+
+### select(...attrs)
+
+Returns an array of rows. Optionally pass column names to override previously set `attr()`.
+
+```javascript
+const rows = await db.table("users").select();
+const rows = await db.table("users").select("id", "name", "email");
+
+// With TypeScript generics
+interface User { id: number; name: string; email: string; }
+const users = await db.table("users").select<User>("id", "name", "email");
+```
+
+### find()
+
+Returns a single row (the first match). Automatically applies `LIMIT 1`.
+
+```javascript
+const user = await db.table("users").where("id", 1).find();
+
+// With TypeScript generics
+const user = await db.table("users").where("id", 1).find<User>();
+```
+
+### count()
+
+Returns the total number of matching rows as a number.
+
+```javascript
+const total = await db.table("users").where("status", "active").count();
+// total is a number
+```
+
+### explain(operator)
+
+Returns the MySQL EXPLAIN result for the query.
+
+```javascript
+const plan = await db.table("users")
+  .where("status", "active")
+  .explain("select");
+// plan is ExplainResult[]
+```
+
+## Write Operations
+
+### insert(row)
+
+Insert a single row.
+
+```javascript
+const result = await db.table("users").insert({
+  name: "Joe",
+  age: 25,
+  email: "joe@example.com",
+});
+// result.insertId -- the auto-increment ID
+// result.affectedRows -- number of rows inserted
+```
+
+### Insert with ON DUPLICATE KEY UPDATE
+
+Use `keys()` to specify unique columns. If a duplicate is found, the operation becomes an update.
+
+```javascript
+const result = await db.table("users").keys("email").insert({
+  email: "joe@example.com",
+  name: "Joe Updated",
+  age: 26,
+});
+```
+
+### insertAll(rows)
+
+Insert multiple rows. Returns an array of results.
+
+```javascript
+const results = await db.table("users").insertAll([
+  { name: "Alice", age: 30 },
+  { name: "Bob", age: 28 },
+  { name: "Charlie", age: 35 },
+]);
+// results is MySQLQueryResult[]
+```
+
+### update(row)
+
+Update rows matching the current where conditions.
+
+```javascript
+const result = await db.table("users")
+  .where("id", 1)
+  .update({ name: "Joe Updated", age: 26 });
+// result.affectedRows -- number of rows updated
+// result.changedRows  -- number of rows actually changed
+```
+
+### delete(id?, index_field_name?)
+
+Delete rows. Can be called with conditions or directly with an ID.
+
+```javascript
+// Delete by conditions
+const result = await db.table("users").where("status", "banned").delete();
+
+// Delete by primary key (defaults to "id" field)
+const result = await db.table("users").delete(1);
+
+// Delete by a custom index field
+const result = await db.table("users").delete(1, "user_id");
+```
+
+### incrBy(attr, increment?)
+
+Increment a column value atomically. Default increment is 1.
+
+```javascript
+// Increment by 1 (default)
+await db.table("users").where("id", 1).incrBy("login_count");
+
+// Increment by a specific number
+await db.table("products").where("id", 1).incrBy("views", 5);
+
+// Increment by string value
+await db.table("users").where("id", 1).incrBy("score", "10");
+
+// Conditional increment with callback
+await db.table("users").where("id", 1).incrBy("error_count", (current) => {
+  return shouldIncrement ? 1 : 0;
+});
+```
+
+### upsertRow(row, condition)
+
+Insert a row or update it if a matching row exists based on the condition.
+
+```javascript
+// Using QueryCondition
+const condition = new QueryCondition();
+condition.where("email", "joe@example.com");
+
+await db.table("users").upsertRow(
+  { email: "joe@example.com", name: "Joe", age: 25 },
+  condition
+);
+```
+
+## Dry Run with notExec()
+
+Call `notExec()` before any CRUD method to get the generated SQL without executing it. Returns a `Builder` with `.sql` and `.values`.
+
+```javascript
+const builder = await db.table("users")
+  .where("status", "active")
+  .orderBy("name", "asc")
+  .limit(10)
+  .notExec()
+  .select("id", "name");
+
+console.log(builder.sql);    // The generated SQL string
+console.log(builder.values); // The parameter values array
+```
+
+This works with all CRUD methods:
+
+```javascript
+const insertBuilder = await db.table("users")
+  .notExec()
+  .insert({ name: "Joe", age: 25 });
+
+const updateBuilder = await db.table("users")
+  .where("id", 1)
+  .notExec()
+  .update({ age: 26 });
+
+const deleteBuilder = await db.table("users")
+  .where("id", 1)
+  .notExec()
+  .delete();
+```
+
+## Complete Example
+
+```javascript
+const db = new QueryHandler(pool);
+
+// Create user
+const insertResult = await db.table("users").insert({
+  name: "Joe",
+  email: "joe@example.com",
+  age: 25,
+});
+const userId = insertResult.insertId;
+
+// Read back
+const user = await db.table("users").where("id", userId).find();
+
+// Update
+await db.table("users").where("id", userId).update({ age: 26 });
+
+// Increment login count
+await db.table("users").where("id", userId).incrBy("login_count");
+
+// Count active users
+const activeCount = await db.table("users").where("status", "active").count();
+
+// Bulk insert
+await db.table("logs").insertAll([
+  { user_id: userId, action: "login" },
+  { user_id: userId, action: "view_profile" },
+]);
+
+// Delete
+await db.table("sessions").where("expired_at", "<", new Date()).delete();
+```

package/skills/query-building.md

@@ -0,0 +1,159 @@
+# Query Building
+
+The `Query` class provides the fluent API for constructing SQL queries. You get a `Query`-based instance (actually `QueryOperator`) from `QueryHandler.table()`.
+
+```javascript
+const query = db.table("users"); // returns QueryOperator (extends Query)
+```
+
+## Table Selection
+
+### Single table
+
+```javascript
+db.table("users");
+db.table("users", "u"); // with alias
+```
+
+### Multiple tables
+
+```javascript
+db.tables(
+  { table: "users", alias: "u" },
+  { table: "orders", alias: "o" }
+);
+```
+
+## Selecting Columns with attr()
+
+```javascript
+// Select specific columns
+query.attr("id", "name", "email");
+
+// Using sub-query as attribute
+const { Query } = require("@axiosleo/orm-mysql");
+
+query.attr(
+  "id",
+  "name",
+  () => {
+    const sub = new Query("select");
+    sub.table("orders").attr("COUNT(*)").where("orders.user_id", "users.id");
+    return sub;
+  }
+);
+```
+
+Calling `attr()` with no arguments clears all previously set attributes.
+
+## Pagination
+
+### limit and offset
+
+```javascript
+query.limit(10);       // LIMIT 10
+query.offset(20);      // OFFSET 20
+```
+
+### page (shorthand)
+
+```javascript
+query.page(10);        // LIMIT 10 OFFSET 0
+query.page(10, 2);     // LIMIT 10 OFFSET 2
+```
+
+## Sorting
+
+```javascript
+query.orderBy("created_at", "desc");
+query.orderBy("name", "asc");
+// Multiple orderBy calls are cumulative
+```
+
+## Grouping and Aggregation
+
+```javascript
+query.groupBy("status");
+query.groupBy("status", "category"); // multiple fields
+
+// HAVING clause (requires groupBy)
+query.groupBy("status").having("COUNT(*)", ">", 5);
+```
+
+## Setting Data
+
+### set() -- for insert/update data
+
+```javascript
+query.set({ name: "Joe", age: 25 });
+```
+
+### keys() -- specify columns for INSERT with ON DUPLICATE KEY UPDATE
+
+```javascript
+query.keys("uuid").insert({
+  uuid: "abc-123",
+  name: "Joe",
+  age: 25,
+});
+// If uuid already exists, the insert becomes an update
+```
+
+## Joins
+
+### leftJoin / rightJoin / innerJoin (preferred)
+
+```javascript
+query.table("users", "u")
+  .leftJoin("orders", "u.id = orders.user_id", { alias: "o" })
+  .attr("u.id", "u.name", "o.total")
+  .select();
+
+query.table("users", "u")
+  .rightJoin("orders", "u.id = orders.user_id")
+  .select();
+
+query.table("users", "u")
+  .innerJoin("roles", "u.role_id = roles.id", { alias: "r" })
+  .select();
+```
+
+### join() -- generic form
+
+```javascript
+query.join({
+  table: "orders",
+  table_alias: "o",
+  self_column: "id",
+  foreign_column: "user_id",
+  join_type: "left",
+});
+```
+
+### Sub-query as join table
+
+```javascript
+const { Query } = require("@axiosleo/orm-mysql");
+
+const subQuery = new Query("select");
+subQuery.table("orders").attr("user_id", "SUM(total) AS order_total").groupBy("user_id");
+
+query.table("users", "u")
+  .leftJoin(subQuery, "u.id = sub.user_id", { alias: "sub" })
+  .select();
+```
+
+## Complete Example
+
+```javascript
+const users = await db.table("users", "u")
+  .attr("u.id", "u.name", "u.email", "o.total")
+  .leftJoin("orders", "u.id = orders.user_id", { alias: "o" })
+  .where("u.status", "active")
+  .whereBetween("u.created_at", ["2024-01-01", "2024-12-31"])
+  .groupBy("u.id")
+  .having("COUNT(o.id)", ">", 0)
+  .orderBy("u.name", "asc")
+  .page(20, 0)
+  .select();
+```

package/skills/transactions.md

@@ -0,0 +1,171 @@
+# Transactions
+
+## Isolation Levels
+
+| Shorthand | Full Name | Description |
+|-----------|-----------|-------------|
+| `RU` | `READ UNCOMMITTED` | Lowest isolation, may read dirty data |
+| `RC` | `READ COMMITTED` | Prevents dirty reads |
+| `RR` | `REPEATABLE READ` | MySQL default, prevents non-repeatable reads |
+| `S` | `SERIALIZABLE` | Highest isolation, full serialization |
+
+## Method 1: Pool + beginTransaction (Recommended)
+
+Use `QueryHandler.beginTransaction()` with a connection pool. The transaction automatically gets its own connection from the pool and releases it on commit/rollback.
+
+```javascript
+const { createPool, QueryHandler } = require("@axiosleo/orm-mysql");
+
+const pool = createPool({
+  host: "localhost",
+  port: 3306,
+  user: "root",
+  password: "password",
+  database: "my_db",
+  connectionLimit: 10,
+});
+
+const db = new QueryHandler(pool);
+
+const tx = await db.beginTransaction({ level: "RC" });
+try {
+  const result = await tx.table("users").insert({ name: "Joe", age: 25 });
+  const userId = result.insertId;
+
+  await tx.table("profiles").insert({ user_id: userId, bio: "Hello" });
+
+  await tx.commit();
+} catch (err) {
+  await tx.rollback();
+  throw err;
+}
+```
+
+## Method 2: TransactionHandler Directly
+
+For more control, create a `TransactionHandler` with a promise connection.
+
+```javascript
+const { TransactionHandler, createPromiseClient } = require("@axiosleo/orm-mysql");
+
+const conn = await createPromiseClient({
+  host: "localhost",
+  port: 3306,
+  user: "root",
+  password: "password",
+  database: "my_db",
+});
+
+const tx = new TransactionHandler(conn, { level: "SERIALIZABLE" });
+await tx.begin();
+
+try {
+  await tx.table("users").insert({ name: "Joe", age: 25 });
+  await tx.commit();
+} catch (err) {
+  await tx.rollback();
+  throw err;
+}
+```
+
+## Row Locking
+
+`TransactionOperator` (returned by `tx.table()`) extends `QueryOperator` with `append()` for SQL suffixes.
+
+### FOR UPDATE
+
+Locks selected rows, preventing other transactions from reading or modifying them.
+
+```javascript
+const tx = await db.beginTransaction({ level: "RC" });
+try {
+  const product = await tx.table("products")
+    .where("sku", "LAPTOP-001")
+    .append("FOR UPDATE")
+    .find();
+
+  if (product.stock < 1) {
+    throw new Error("Out of stock");
+  }
+
+  await tx.table("products")
+    .where("sku", "LAPTOP-001")
+    .update({ stock: product.stock - 1 });
+
+  await tx.table("orders").insert({
+    product_id: product.id,
+    quantity: 1,
+    total: product.price,
+  });
+
+  await tx.commit();
+} catch (err) {
+  await tx.rollback();
+  throw err;
+}
+```
+
+### LOCK IN SHARE MODE
+
+Allows other transactions to read but not modify the locked rows.
+
+```javascript
+const rows = await tx.table("products")
+  .where("category", "electronics")
+  .append("LOCK IN SHARE MODE")
+  .select();
+```
+
+## TransactionHandler API
+
+| Method | Description |
+|--------|-------------|
+| `begin()` | Start the transaction |
+| `commit()` | Commit and release the connection |
+| `rollback()` | Rollback and release the connection |
+| `table(name, alias?)` | Returns `TransactionOperator` for the table |
+| `query(options)` | Execute raw SQL within the transaction |
+| `execute(sql, values)` | Execute parameterized SQL |
+| `lastInsertId(alias?)` | Get the last auto-increment ID |
+| `upsert(table, data, condition)` | Insert or update within the transaction |
+
+## Concurrent Transactions
+
+With a connection pool, multiple transactions run on separate connections without blocking each other.
+
+```javascript
+const db = new QueryHandler(pool);
+
+await Promise.all([
+  (async () => {
+    const tx = await db.beginTransaction();
+    try {
+      await tx.table("users").insert({ name: "User1" });
+      await tx.commit();
+    } catch (err) {
+      await tx.rollback();
+      throw err;
+    }
+  })(),
+
+  (async () => {
+    const tx = await db.beginTransaction();
+    try {
+      await tx.table("users").insert({ name: "User2" });
+      await tx.commit();
+    } catch (err) {
+      await tx.rollback();
+      throw err;
+    }
+  })(),
+]);
+```
+
+## Best Practices
+
+1. **Use connection pools in production** -- prevents connection exhaustion
+2. **Always wrap in try/catch** -- ensure rollback on errors
+3. **Keep transactions short** -- avoid long-running operations inside transactions
+4. **Choose the right isolation level** -- `RC` is a good default for most cases
+5. **Use row locking when needed** -- `FOR UPDATE` prevents concurrent modification conflicts
+6. **Prefer `beginTransaction()` over manual `TransactionHandler`** -- automatic connection management

package/skills/where-conditions.md

@@ -0,0 +1,146 @@
+# Where Conditions
+
+The `QueryCondition` class provides all WHERE clause methods. All methods return `this` for chaining.
+
+## Basic where()
+
+### Key-value equality
+
+```javascript
+query.where("name", "Joe");          // WHERE `name` = ?
+query.where("age", ">", 18);         // WHERE `age` > ?
+query.where("status", "!=", "banned"); // WHERE `status` != ?
+```
+
+### Object form (multiple equalities)
+
+```javascript
+query.where({ name: "Joe", status: "active" });
+// WHERE `name` = ? AND `status` = ?
+```
+
+### Supported operators
+
+`=`, `!=`, `>`, `<`, `>=`, `<=`, `LIKE`, `NOT LIKE`, `IN`, `NOT IN`, `BETWEEN`, `NOT BETWEEN`, `IS`, `IS NOT`, `REGEXP`, `NOT REGEXP`, `CONTAIN`, `NOT CONTAIN`, `OVERLAPS`, `NOT OVERLAPS`
+
+## Logical Operators
+
+### AND / OR grouping
+
+```javascript
+// Switch to OR logic for subsequent conditions
+query.where("OR");
+// or equivalently:
+query.whereOr();
+
+// Switch back to AND logic
+query.where("AND");
+// or equivalently:
+query.whereAnd();
+```
+
+### Combining AND/OR
+
+```javascript
+// WHERE `status` = ? AND (`age` > ? OR `vip` = ?)
+query
+  .where("status", "active")
+  .whereOr()
+  .where("age", ">", 18)
+  .where("vip", true)
+  .whereAnd();
+```
+
+## IN / NOT IN
+
+```javascript
+query.whereIn("status", ["active", "pending"]);
+// WHERE `status` IN (?, ?)
+
+query.whereNotIn("role", ["banned", "suspended"]);
+// WHERE `role` NOT IN (?, ?)
+```
+
+### Sub-query in whereIn
+
+```javascript
+const { Query } = require("@axiosleo/orm-mysql");
+
+const subQuery = new Query("select");
+subQuery.table("orders").attr("user_id").where("total", ">", 100);
+
+query.whereIn("id", subQuery);
+// WHERE `id` IN (SELECT `user_id` FROM `orders` WHERE `total` > ?)
+```
+
+## LIKE / NOT LIKE
+
+```javascript
+query.whereLike("name", "%Joe%");
+// WHERE `name` LIKE ?
+
+query.whereNotLike("email", "%spam%");
+
+// Multiple patterns (OR)
+query.whereLike("name", ["%Joe%", "%Jane%"]);
+```
+
+## BETWEEN / NOT BETWEEN
+
+```javascript
+query.whereBetween("age", [18, 65]);
+// WHERE `age` BETWEEN ? AND ?
+
+query.whereNotBetween("created_at", ["2024-01-01", "2024-06-30"]);
+```
+
+## CONTAIN / NOT CONTAIN
+
+For JSON array or SET column checks:
+
+```javascript
+query.whereContain("tags", "javascript");
+// WHERE JSON_CONTAINS(`tags`, ?)
+
+query.whereNotContain("tags", "deprecated");
+```
+
+## OVERLAPS / NOT OVERLAPS
+
+For JSON array overlap checks:
+
+```javascript
+query.whereOverlaps("categories", [1, 2, 3]);
+
+query.whereNotOverlaps("categories", [4, 5]);
+```
+
+## Nested Conditions with whereCondition()
+
+Use `QueryCondition` to build complex nested conditions:
+
+```javascript
+const { QueryCondition } = require("@axiosleo/orm-mysql");
+
+const nested = new QueryCondition();
+nested.where("age", ">", 18).where("age", "<", 65);
+
+query
+  .where("status", "active")
+  .whereCondition(nested);
+// WHERE `status` = ? AND (`age` > ? AND `age` < ?)
+```
+
+## Complete Example
+
+```javascript
+const results = await db.table("products", "p")
+  .where("p.status", "active")
+  .whereBetween("p.price", [10, 100])
+  .whereIn("p.category_id", [1, 2, 3])
+  .whereLike("p.name", "%phone%")
+  .whereNotIn("p.id", blockedIds)
+  .orderBy("p.price", "asc")
+  .page(20, 0)
+  .select();
+```