sqlstack 1.0.21 → 1.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sqlstack",
-  "version": "1.0.21",
+  "version": "1.0.22",
   "description": "",
   "license": "ISC",
   "author": "",

package/readme.md

@@ -14,6 +14,7 @@ Write real SQL next to your code, and use small, composable decorators to bind,
 - [How It Works](#how-it-works)
 - [Result Types](#result-types)
 - [Error Handling](#error-handling)
+- [Transactions](#transactions)
 - [Inline SQL](#inline-sql)
 - [Advanced: Direct Database Access](#advanced-direct-database-access)
 - [Database Support](#database-support)
@@ -897,6 +898,289 @@ Available error classes:
 
 ---
 
+## Transactions
+
+Run multiple queries as a single atomic unit. If any query fails, all changes are rolled back automatically.
+
+### Basic Usage with `@transaction` Decorator
+
+Mark a method with `@transaction` to wrap it in a transaction:
+
+```ts
+import { transaction, currentTransaction } from "sqlstack";
+
+class UserService {
+  @transaction
+  async createUserWithProfile(data: { email: string; name: string }) {
+    await this.usersRepo.insert(data);
+    await this.profilesRepo.insert({ userId: data.id, bio: "" });
+  }
+}
+
+// If either insert fails, both are rolled back
+await new UserService().createUserWithProfile({ email: "alice@example.com", name: "Alice" });
+```
+
+Queries in `@Query` decorated methods automatically participate in the active transaction:
+
+```ts
+@QueryBinder()
+class UsersRepo {
+  @Query({ sql: 'INSERT INTO users (email, name) VALUES (:email, :name)' })
+  async insert(data: { email: string; name: string }): Promise<WriteResult> {
+    throw new Error("replaced by @Query");
+  }
+}
+
+@QueryBinder()
+class ProfilesRepo {
+  @Query({ sql: 'INSERT INTO profiles (user_id, bio) VALUES (:userId, :bio)' })
+  async insert(data: { userId: string; bio: string }): Promise<WriteResult> {
+    throw new Error("replaced by @Query");
+  }
+}
+```
+
+### Commit and Rollback
+
+**Commit on success:** If the transaction method returns normally, all queries are committed.
+
+**Rollback on error:** If the method throws, all queries are rolled back and the error is rethrown:
+
+```ts
+class UserService {
+  @transaction
+  async createUser() {
+    await this.usersRepo.insert({ email: "bob@example.com" });
+    throw new Error("something went wrong");
+    // Rollback happens here; insert is undone
+  }
+}
+
+await new UserService().createUser(); // throws "something went wrong"
+```
+
+### Lazy Transactions
+
+By default, transactions use **lazy mode**: they don't start (no `BEGIN`) until the first query runs. This avoids overhead if the method never queries:
+
+```ts
+@transaction({ lazy: true })  // default behavior
+async readOnlyOperation() {
+  // No database transaction started yet
+  const data = await this.repo.fetch();
+
+  // Process data without holding a transaction
+  return processData(data);
+}
+```
+
+Disable lazy mode with `lazy: false` to start the transaction immediately:
+
+```ts
+@transaction({ lazy: false })
+async mustStartTransaction() {
+  // BEGIN is executed immediately, even before first query
+}
+```
+
+### Accessing the Current Transaction
+
+Use `currentTransaction()` to access the active transaction context within a method:
+
+```ts
+class UserService {
+  @transaction
+  async createUserWithValidation(data: { email: string }) {
+    const user = await this.usersRepo.insert(data);
+
+    // Validate user was inserted
+    const check = await this.usersRepo.findById(user.id);
+    if (!check) {
+      // Mark transaction for rollback and throw a custom error
+      currentTransaction()?.rollbackOnly(new Error("User not found after insert"));
+      return; // exit gracefully
+    }
+
+    return user;
+  }
+}
+```
+
+### Rollback with Custom Error
+
+Use `rollbackOnly(error)` to mark a transaction for rollback while specifying which error should be thrown:
+
+```ts
+class UserService {
+  @transaction
+  async createUser(email: string) {
+    try {
+      await this.usersRepo.insert({ email });
+    } catch (dbError) {
+      // Roll back and throw a sanitized error
+      currentTransaction()?.rollbackOnly(new Error("Failed to create user"));
+      return; // rethrow happens automatically
+    }
+  }
+}
+```
+
+You can also throw `RollbackTransactionError` to explicitly signal rollback while optionally wrapping another error:
+
+```ts
+import { RollbackTransactionError } from "sqlstack";
+
+class UserService {
+  @transaction
+  async createUser(email: string) {
+    await this.usersRepo.insert({ email });
+
+    // Roll back and throw the wrapped error
+    throw new RollbackTransactionError("Transaction cancelled", new Error("User rejected"));
+    // Caller sees: Error("User rejected")
+  }
+}
+```
+
+### Using `withTransaction()` Function
+
+For programmatic control, use the `withTransaction()` function:
+
+```ts
+import { withTransaction } from "sqlstack";
+
+const result = await withTransaction(async () => {
+  const user = await this.usersRepo.insert({ email: "charlie@example.com" });
+  await this.profilesRepo.insert({ userId: user.id });
+  return user;
+}, { db: "primary" });
+```
+
+### Multiple Databases
+
+Transactions are per-database. Run transactions on different databases simultaneously:
+
+```ts
+class MultiDbService {
+  @transaction({ db: "primary" })
+  async insertUser() {
+    await this.usersRepo.insert({ email: "dave@example.com" });
+  }
+
+  @transaction({ db: "analytics" })
+  async logAnalytics() {
+    await this.analyticsRepo.insert({ event: "user_created" });
+  }
+}
+
+// Both transactions run independently
+await Promise.all([
+  new MultiDbService().insertUser(),
+  new MultiDbService().logAnalytics(),
+]);
+```
+
+### Nested Transactions (Savepoints)
+
+Multiple `@transaction` decorators stack safely. Only the outermost transaction commits/rolls back:
+
+```ts
+class UserService {
+  @transaction
+  async createUser(email: string) {
+    await this.usersRepo.insert({ email });
+    await this.createDefaultProfile();
+  }
+
+  @transaction  // nested decorator
+  async createDefaultProfile() {
+    await this.profilesRepo.insert({ name: "Default Profile" });
+  }
+}
+
+// Outer transaction commits both inserts
+await new UserService().createUser("eve@example.com");
+```
+
+All queries use the same transaction context. If the inner method throws, the outer transaction rolls back everything.
+
+### Connection Pooling and Resource Cleanup
+
+For **Postgres** and **MySQL**, transactions acquire connections from the pool and release them when complete:
+
+**Postgres:**
+```ts
+import { createPgDb } from "sqlstack/adapters";
+import { Pool } from "pg";
+
+const pool = new Pool({ connectionString: process.env.PG_URL });
+SqlStackDB.register("primary", createPgDb(pool));
+
+class UserService {
+  @transaction({ db: "primary" })
+  async createUser() {
+    // A client is acquired from the pool for this transaction
+    await this.usersRepo.insert({ email: "frank@example.com" });
+    // Client is released back to the pool after commit/rollback
+  }
+}
+```
+
+**MySQL:**
+```ts
+import { createMysqlDb } from "sqlstack/adapters";
+import mysql from "mysql2/promise";
+
+const pool = mysql.createPool({ uri: process.env.MYSQL_URL });
+SqlStackDB.register("primary", createMysqlDb(pool));
+
+class UserService {
+  @transaction({ db: "primary" })
+  async createUser() {
+    // A connection is acquired from the pool
+    await this.usersRepo.insert({ email: "grace@example.com" });
+    // Connection is released back to the pool
+  }
+}
+```
+
+**SQLite** uses the existing connection (better-sqlite3 doesn't support pooling).
+
+### Error Handling in Transactions
+
+Errors are always rethrown after rollback:
+
+```ts
+class UserService {
+  @transaction
+  async createUser() {
+    await this.usersRepo.insert({ email: "henry@example.com" });
+    throw new Error("oops");
+    // Rollback happens, then "oops" is thrown to caller
+  }
+}
+
+try {
+  await new UserService().createUser();
+} catch (err) {
+  console.error(err.message); // "oops"
+}
+```
+
+If rollback itself fails, that error is thrown (and the original error is lost):
+
+```ts
+@transaction
+async createUser() {
+  await this.usersRepo.insert({ email: "ivan@example.com" });
+  throw new Error("original error");
+  // If ROLLBACK SQL fails, the rollback error is thrown instead
+}
+```
+
+---
+
 ## Inline SQL
 
 For simple or dynamic queries, use `@Query({ sql: "..." })` with inline SQL: