sqlstack 1.0.20 → 1.0.22

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,aAAa;AACb,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC;AAE3C,WAAW;AACX,cAAc,YAAY,CAAC;AAE3B,wBAAwB;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AAEjC,aAAa;AACb,cAAc,aAAa,CAAC;AAI5B,OAAO,EAAE,UAAU,EAAY,MAAM,YAAY,CAAC;AAElD,mDAAmD;AACnD,cAAc,qBAAqB,CAAC","sourcesContent":["// Decorators\nexport * from './decorators/queryBinder';\nexport * from './decorators/query';\nexport * from './decorators/defaults';\nexport * from './decorators/resultShape';\nexport * from './decorators/validateResult';\nexport * from './decorators/transform';\nexport * from './decorators/page';\nexport * from './decorators/missingAsNull';\n\n// Adapters\nexport * from './adapters';\n\n// Errors and Validation\nexport * from './core/errors';\nexport * from './core/validator';\n\n// DTO Helper\nexport * from './utils/dto';\n\n// Database Registry and Types\nexport type { Dialect, WriteResult, PostgresWriteResult, QueryResult, Database } from './registry';\nexport { SqlStackDB, IStackDB } from './registry';\n\n// Legacy exports (kept for backward compatibility)\nexport * from './binders/sqlBinder';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,aAAa;AACb,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC;AAE3C,eAAe;AACf,cAAc,gBAAgB,CAAC;AAE/B,WAAW;AACX,cAAc,YAAY,CAAC;AAE3B,wBAAwB;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AAEjC,aAAa;AACb,cAAc,aAAa,CAAC;AAI5B,OAAO,EAAE,UAAU,EAAY,MAAM,YAAY,CAAC;AAElD,mDAAmD;AACnD,cAAc,qBAAqB,CAAC","sourcesContent":["// Decorators\nexport * from './decorators/queryBinder';\nexport * from './decorators/query';\nexport * from './decorators/defaults';\nexport * from './decorators/resultShape';\nexport * from './decorators/validateResult';\nexport * from './decorators/transform';\nexport * from './decorators/page';\nexport * from './decorators/missingAsNull';\n\n// Transactions\nexport * from './transactions';\n\n// Adapters\nexport * from './adapters';\n\n// Errors and Validation\nexport * from './core/errors';\nexport * from './core/validator';\n\n// DTO Helper\nexport * from './utils/dto';\n\n// Database Registry and Types\nexport type { Dialect, WriteResult, PostgresWriteResult, QueryResult, Database } from './registry';\nexport { SqlStackDB, IStackDB } from './registry';\n\n// Legacy exports (kept for backward compatibility)\nexport * from './binders/sqlBinder';\n"]}

package/dist/esm/registry.js

@@ -12,14 +12,17 @@ class Registry {
         this.defaultName = name;
         return this;
     }
-    get(name) {
+    getEntry(name) {
         const key = name ?? this.defaultName;
         if (!key)
             throw new Error('No default database set');
         const db = this.map.get(key);
         if (!db)
             throw new Error(`No database registered under ${key}`);
-        return db;
+        return { name: key, db };
+    }
+    get(name) {
+        return this.getEntry(name).db;
     }
 }
 // Ensure a single shared instance across module copies/usages

package/dist/esm/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/registry.ts"],"names":[],"mappings":"AAwBA,MAAM,QAAQ;IAAd;QACU,QAAG,GAAG,IAAI,GAAG,EAAoB,CAAC;IAqB5C,CAAC;IAlBC,QAAQ,CAAC,IAAY,EAAE,EAAY;QACjC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,UAAU,CAAC,IAAY;QACrB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,IAAI,EAAE,CAAC,CAAC;QACjF,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QACxB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,GAAG,CAAC,IAAa;QACf,MAAM,GAAG,GAAG,IAAI,IAAI,IAAI,CAAC,WAAW,CAAC;QACrC,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;QACrD,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,GAAG,EAAE,CAAC,CAAC;QAChE,OAAO,EAAE,CAAC;IACZ,CAAC;CACF;AAED,8DAA8D;AAC9D,MAAM,CAAC,GAAG,UAAiB,CAAC;AAC5B,IAAI,CAAC,CAAC,CAAC,sBAAsB,EAAE,CAAC;IAC9B,CAAC,CAAC,sBAAsB,GAAG,IAAI,QAAQ,EAAE,CAAC;AAC5C,CAAC;AAED,MAAM,CAAC,MAAM,UAAU,GAAa,CAAC,CAAC,sBAAsB,CAAC","sourcesContent":["export type Dialect = 'sqlite' | 'mysql' | 'postgres';\n\n// Result for non-SELECT statements across adapters\nexport interface WriteResult {\n  rowsAffected: number;\n  lastInsertId?: unknown;\n}\n\n// Postgres-specific extension when using RETURNING on write statements\nexport interface PostgresWriteResult extends WriteResult {\n  // Only present when the SQL includes RETURNING and rows are returned\n  returning?: any[];\n}\n\nexport type QueryResult = any[] | WriteResult | PostgresWriteResult;\n\nexport interface Database {\n  dialect: Dialect;\n  query(sql: string, params: unknown[]): Promise<QueryResult>;\n  // Underlying driver connection or pool (driver-specific)\n  conn: unknown;\n  close: () => Promise<void> | void;\n}\n\nclass Registry {\n  private map = new Map<string, Database>();\n  private defaultName?: string;\n\n  register(name: string, db: Database) {\n    this.map.set(name, db);\n    return this;\n  }\n\n  setDefault(name: string) {\n    if (!this.map.has(name)) throw new Error(`No database registered under ${name}`);\n    this.defaultName = name;\n    return this;\n  }\n\n  get(name?: string): Database {\n    const key = name ?? this.defaultName;\n    if (!key) throw new Error('No default database set');\n    const db = this.map.get(key);\n    if (!db) throw new Error(`No database registered under ${key}`);\n    return db;\n  }\n}\n\n// Ensure a single shared instance across module copies/usages\nconst g = globalThis as any;\nif (!g.__SQLSTACK_SINGLETON__) {\n  g.__SQLSTACK_SINGLETON__ = new Registry();\n}\n\nexport const SqlStackDB: Registry = g.__SQLSTACK_SINGLETON__;\n\nexport type IStackDB = typeof SqlStackDB;\n"]}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/registry.ts"],"names":[],"mappings":"AAwBA,MAAM,QAAQ;IAAd;QACU,QAAG,GAAG,IAAI,GAAG,EAAoB,CAAC;IAyB5C,CAAC;IAtBC,QAAQ,CAAC,IAAY,EAAE,EAAY;QACjC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,UAAU,CAAC,IAAY;QACrB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,IAAI,EAAE,CAAC,CAAC;QACjF,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QACxB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,QAAQ,CAAC,IAAa;QACpB,MAAM,GAAG,GAAG,IAAI,IAAI,IAAI,CAAC,WAAW,CAAC;QACrC,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;QACrD,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,GAAG,EAAE,CAAC,CAAC;QAChE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC;IAC3B,CAAC;IAED,GAAG,CAAC,IAAa;QACf,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;IAChC,CAAC;CACF;AAED,8DAA8D;AAC9D,MAAM,CAAC,GAAG,UAAiB,CAAC;AAC5B,IAAI,CAAC,CAAC,CAAC,sBAAsB,EAAE,CAAC;IAC9B,CAAC,CAAC,sBAAsB,GAAG,IAAI,QAAQ,EAAE,CAAC;AAC5C,CAAC;AAED,MAAM,CAAC,MAAM,UAAU,GAAa,CAAC,CAAC,sBAAsB,CAAC","sourcesContent":["export type Dialect = 'sqlite' | 'mysql' | 'postgres';\n\n// Result for non-SELECT statements across adapters\nexport interface WriteResult {\n  rowsAffected: number;\n  lastInsertId?: unknown;\n}\n\n// Postgres-specific extension when using RETURNING on write statements\nexport interface PostgresWriteResult extends WriteResult {\n  // Only present when the SQL includes RETURNING and rows are returned\n  returning?: any[];\n}\n\nexport type QueryResult = any[] | WriteResult | PostgresWriteResult;\n\nexport interface Database {\n  dialect: Dialect;\n  query(sql: string, params: unknown[]): Promise<QueryResult>;\n  // Underlying driver connection or pool (driver-specific)\n  conn: unknown;\n  close: () => Promise<void> | void;\n}\n\nclass Registry {\n  private map = new Map<string, Database>();\n  private defaultName?: string;\n\n  register(name: string, db: Database) {\n    this.map.set(name, db);\n    return this;\n  }\n\n  setDefault(name: string) {\n    if (!this.map.has(name)) throw new Error(`No database registered under ${name}`);\n    this.defaultName = name;\n    return this;\n  }\n\n  getEntry(name?: string): { name: string; db: Database } {\n    const key = name ?? this.defaultName;\n    if (!key) throw new Error('No default database set');\n    const db = this.map.get(key);\n    if (!db) throw new Error(`No database registered under ${key}`);\n    return { name: key, db };\n  }\n\n  get(name?: string): Database {\n    return this.getEntry(name).db;\n  }\n}\n\n// Ensure a single shared instance across module copies/usages\nconst g = globalThis as any;\nif (!g.__SQLSTACK_SINGLETON__) {\n  g.__SQLSTACK_SINGLETON__ = new Registry();\n}\n\nexport const SqlStackDB: Registry = g.__SQLSTACK_SINGLETON__;\n\nexport type IStackDB = typeof SqlStackDB;\n"]}

package/dist/esm/transactions.js

@@ -0,0 +1,268 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _TransactionHandle_state, _TransactionHandle_owned, _TransactionHandle_finished;
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { SqlStackDB } from './registry.js';
+import { createPgDb, createMysqlDb } from './adapters/index.js';
+import { RollbackTransactionError, SqlStackError } from './core/errors.js';
+const als = new AsyncLocalStorage();
+function getStore() {
+    return als.getStore();
+}
+function getOrCreateStore() {
+    const existing = getStore();
+    if (existing)
+        return { store: existing, isNew: false };
+    return { store: { txByDb: new Map() }, isNew: true };
+}
+function isRollbackTransactionError(err) {
+    return err instanceof RollbackTransactionError;
+}
+function unwrapRollbackCause(err) {
+    return typeof err.cause === 'undefined' ? err : err.cause;
+}
+export class TransactionHandle {
+    constructor(dbName, state, owned) {
+        _TransactionHandle_state.set(this, void 0);
+        _TransactionHandle_owned.set(this, void 0);
+        _TransactionHandle_finished.set(this, false);
+        this.dbName = dbName;
+        __classPrivateFieldSet(this, _TransactionHandle_state, state, "f");
+        __classPrivateFieldSet(this, _TransactionHandle_owned, owned, "f");
+    }
+    async ensureStarted() {
+        await __classPrivateFieldGet(this, _TransactionHandle_state, "f").ensureStarted();
+    }
+    rollbackOnly(errorToThrow) {
+        __classPrivateFieldGet(this, _TransactionHandle_state, "f").rollbackOnly = true;
+        if (typeof errorToThrow !== 'undefined') {
+            __classPrivateFieldGet(this, _TransactionHandle_state, "f").rollbackError = errorToThrow;
+        }
+    }
+    async commit() {
+        if (!__classPrivateFieldGet(this, _TransactionHandle_owned, "f"))
+            return;
+        await __classPrivateFieldGet(this, _TransactionHandle_state, "f").commitIfStarted();
+    }
+    async rollback() {
+        if (!__classPrivateFieldGet(this, _TransactionHandle_owned, "f"))
+            return;
+        await __classPrivateFieldGet(this, _TransactionHandle_state, "f").rollbackIfStarted();
+    }
+    async release() {
+        if (!__classPrivateFieldGet(this, _TransactionHandle_owned, "f"))
+            return;
+        await __classPrivateFieldGet(this, _TransactionHandle_state, "f").release();
+    }
+    async finishOnSuccess() {
+        if (!__classPrivateFieldGet(this, _TransactionHandle_owned, "f") || __classPrivateFieldGet(this, _TransactionHandle_finished, "f"))
+            return;
+        __classPrivateFieldSet(this, _TransactionHandle_finished, true, "f");
+        await __classPrivateFieldGet(this, _TransactionHandle_state, "f").finishOnSuccess();
+    }
+    async finishOnError(err) {
+        if (!__classPrivateFieldGet(this, _TransactionHandle_owned, "f") || __classPrivateFieldGet(this, _TransactionHandle_finished, "f"))
+            return;
+        __classPrivateFieldSet(this, _TransactionHandle_finished, true, "f");
+        await __classPrivateFieldGet(this, _TransactionHandle_state, "f").finishOnError(err);
+    }
+}
+_TransactionHandle_state = new WeakMap(), _TransactionHandle_owned = new WeakMap(), _TransactionHandle_finished = new WeakMap();
+class TxState {
+    constructor(dbName, db, options) {
+        this.depth = 1;
+        this.started = false;
+        this.completed = false;
+        this.rollbackOnly = false;
+        this.dbName = dbName;
+        this.db = db;
+        this.options = {
+            lazy: options?.lazy ?? true,
+            nested: options?.nested ?? 'join',
+        };
+    }
+    get activeDb() {
+        return this.txDb ?? this.db;
+    }
+    async ensureStarted() {
+        if (this.started)
+            return;
+        const dialect = this.db.dialect ?? 'sqlite';
+        if (dialect === 'postgres') {
+            const pool = this.db.conn;
+            if (!pool || typeof pool.connect !== 'function') {
+                throw new SqlStackError('Postgres transactions require a pg Pool with .connect() as Database.conn');
+            }
+            const client = await pool.connect();
+            this.txDb = createPgDb(client);
+            this.releaseFn = async () => {
+                if (typeof client.release === 'function')
+                    client.release();
+            };
+            await this.txDb.query('BEGIN', []);
+            this.started = true;
+            return;
+        }
+        if (dialect === 'mysql') {
+            const pool = this.db.conn;
+            if (!pool || typeof pool.getConnection !== 'function') {
+                throw new SqlStackError('MySQL transactions require a mysql2 Pool with .getConnection() as Database.conn');
+            }
+            const conn = await pool.getConnection();
+            this.txDb = createMysqlDb(conn);
+            this.releaseFn = async () => {
+                if (typeof conn.release === 'function')
+                    conn.release();
+            };
+            await this.txDb.query('START TRANSACTION', []);
+            this.started = true;
+            return;
+        }
+        // sqlite: existing connection is already bound
+        await this.db.query('BEGIN', []);
+        this.started = true;
+    }
+    async query(sql, params) {
+        await this.ensureStarted();
+        return await this.activeDb.query(sql, params);
+    }
+    async commitIfStarted() {
+        if (this.completed)
+            return;
+        if (!this.started) {
+            this.completed = true;
+            return;
+        }
+        await this.activeDb.query('COMMIT', []);
+        this.completed = true;
+    }
+    async rollbackIfStarted() {
+        if (this.completed)
+            return;
+        if (!this.started) {
+            this.completed = true;
+            return;
+        }
+        await this.activeDb.query('ROLLBACK', []);
+        this.completed = true;
+    }
+    async release() {
+        try {
+            if (this.releaseFn)
+                await this.releaseFn();
+        }
+        finally {
+            this.txDb = undefined;
+            this.releaseFn = undefined;
+        }
+    }
+    async finishOnSuccess() {
+        try {
+            if (this.rollbackOnly) {
+                await this.rollbackIfStarted();
+                if (typeof this.rollbackError !== 'undefined')
+                    throw this.rollbackError;
+                throw new RollbackTransactionError();
+            }
+            await this.commitIfStarted();
+        }
+        finally {
+            await this.release();
+        }
+    }
+    async finishOnError(err) {
+        try {
+            await this.rollbackIfStarted();
+        }
+        finally {
+            await this.release();
+        }
+        if (isRollbackTransactionError(err)) {
+            throw unwrapRollbackCause(err);
+        }
+        throw err;
+    }
+}
+function enterTx(dbName, options) {
+    const { store, isNew } = getOrCreateStore();
+    const existing = store.txByDb.get(dbName);
+    if (existing) {
+        existing.depth++;
+        return { handle: new TransactionHandle(dbName, existing, false), store, isNewStore: isNew };
+    }
+    const { db } = SqlStackDB.getEntry(dbName);
+    const state = new TxState(dbName, db, options);
+    store.txByDb.set(dbName, state);
+    return { handle: new TransactionHandle(dbName, state, true), store, isNewStore: isNew };
+}
+async function exitTx(dbName, store) {
+    const state = store.txByDb.get(dbName);
+    if (!state)
+        return;
+    state.depth = Math.max(0, state.depth - 1);
+    if (state.depth === 0) {
+        store.txByDb.delete(dbName);
+    }
+}
+export function currentTransaction(db) {
+    const store = getStore();
+    if (!store)
+        return undefined;
+    const resolved = SqlStackDB.getEntry(db).name;
+    const state = store.txByDb.get(resolved);
+    if (!state)
+        return undefined;
+    return new TransactionHandle(resolved, state, false);
+}
+export async function withTransaction(fn, options) {
+    const resolved = SqlStackDB.getEntry(options?.db).name;
+    const { handle, store, isNewStore } = enterTx(resolved, options);
+    const run = async () => {
+        try {
+            const out = await fn();
+            await handle.finishOnSuccess();
+            return out;
+        }
+        catch (err) {
+            await handle.finishOnError(err);
+            throw err;
+        }
+        finally {
+            await exitTx(resolved, store);
+        }
+    };
+    return isNewStore ? await als.run(store, run) : await run();
+}
+export const transaction = function (...args) {
+    // @transaction
+    if (args.length === 3 && typeof args[2]?.value === 'function') {
+        const [target, prop, desc] = args;
+        wrapMethod(target, prop, desc, undefined);
+        return;
+    }
+    // @transaction() or @transaction({ ... })
+    const options = args.length > 0 ? args[0] : undefined;
+    return function (target, prop, desc) {
+        wrapMethod(target, prop, desc, options);
+    };
+};
+function wrapMethod(_target, _prop, desc, options) {
+    const original = desc.value;
+    desc.value = async function (...callArgs) {
+        return await withTransaction(() => original.apply(this, callArgs), options);
+    };
+}
+export function getActiveTransaction(dbName) {
+    const store = getStore();
+    return store?.txByDb.get(dbName);
+}
+//# sourceMappingURL=transactions.js.map

package/dist/esm/transactions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactions.js","sourceRoot":"","sources":["../../src/transactions.ts"],"names":[],"mappings":"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","sourcesContent":["import { AsyncLocalStorage } from 'node:async_hooks';\nimport type { Database, QueryResult } from './registry';\nimport { SqlStackDB } from './registry';\nimport { createPgDb, createMysqlDb } from './adapters';\nimport { RollbackTransactionError, SqlStackError } from './core/errors';\n\nexport type TransactionOptions = {\n  db?: string;\n  lazy?: boolean;\n  nested?: 'join';\n};\n\ntype TxStore = {\n  txByDb: Map<string, TxState>;\n};\n\nconst als = new AsyncLocalStorage<TxStore>();\n\nfunction getStore(): TxStore | undefined {\n  return als.getStore();\n}\n\nfunction getOrCreateStore(): { store: TxStore; isNew: boolean } {\n  const existing = getStore();\n  if (existing) return { store: existing, isNew: false };\n  return { store: { txByDb: new Map() }, isNew: true };\n}\n\nfunction isRollbackTransactionError(err: unknown): err is RollbackTransactionError {\n  return err instanceof RollbackTransactionError;\n}\n\nfunction unwrapRollbackCause(err: RollbackTransactionError): unknown {\n  return typeof err.cause === 'undefined' ? err : err.cause;\n}\n\nexport class TransactionHandle {\n  readonly dbName: string;\n  #state: TxState;\n  #owned: boolean;\n  #finished = false;\n\n  constructor(dbName: string, state: TxState, owned: boolean) {\n    this.dbName = dbName;\n    this.#state = state;\n    this.#owned = owned;\n  }\n\n  async ensureStarted() {\n    await this.#state.ensureStarted();\n  }\n\n  rollbackOnly(errorToThrow?: unknown) {\n    this.#state.rollbackOnly = true;\n    if (typeof errorToThrow !== 'undefined') {\n      this.#state.rollbackError = errorToThrow;\n    }\n  }\n\n  async commit() {\n    if (!this.#owned) return;\n    await this.#state.commitIfStarted();\n  }\n\n  async rollback() {\n    if (!this.#owned) return;\n    await this.#state.rollbackIfStarted();\n  }\n\n  async release() {\n    if (!this.#owned) return;\n    await this.#state.release();\n  }\n\n  async finishOnSuccess() {\n    if (!this.#owned || this.#finished) return;\n    this.#finished = true;\n    await this.#state.finishOnSuccess();\n  }\n\n  async finishOnError(err: unknown) {\n    if (!this.#owned || this.#finished) return;\n    this.#finished = true;\n    await this.#state.finishOnError(err);\n  }\n}\n\nclass TxState {\n  readonly dbName: string;\n  readonly db: Database;\n  readonly options: Required<Pick<TransactionOptions, 'lazy'>> & Pick<TransactionOptions, 'nested'>;\n  depth = 1;\n  started = false;\n  completed = false;\n  rollbackOnly = false;\n  rollbackError: unknown | undefined;\n\n  private txDb: Database | undefined;\n  private releaseFn: (() => Promise<void>) | undefined;\n\n  constructor(dbName: string, db: Database, options: TransactionOptions | undefined) {\n    this.dbName = dbName;\n    this.db = db;\n    this.options = {\n      lazy: options?.lazy ?? true,\n      nested: options?.nested ?? 'join',\n    };\n  }\n\n  get activeDb(): Database {\n    return this.txDb ?? this.db;\n  }\n\n  async ensureStarted() {\n    if (this.started) return;\n\n    const dialect = this.db.dialect ?? 'sqlite';\n    if (dialect === 'postgres') {\n      const pool: any = this.db.conn;\n      if (!pool || typeof pool.connect !== 'function') {\n        throw new SqlStackError('Postgres transactions require a pg Pool with .connect() as Database.conn');\n      }\n      const client = await pool.connect();\n      this.txDb = createPgDb(client);\n      this.releaseFn = async () => {\n        if (typeof client.release === 'function') client.release();\n      };\n      await this.txDb.query('BEGIN', []);\n      this.started = true;\n      return;\n    }\n\n    if (dialect === 'mysql') {\n      const pool: any = this.db.conn;\n      if (!pool || typeof pool.getConnection !== 'function') {\n        throw new SqlStackError('MySQL transactions require a mysql2 Pool with .getConnection() as Database.conn');\n      }\n      const conn = await pool.getConnection();\n      this.txDb = createMysqlDb(conn);\n      this.releaseFn = async () => {\n        if (typeof conn.release === 'function') conn.release();\n      };\n      await this.txDb.query('START TRANSACTION', []);\n      this.started = true;\n      return;\n    }\n\n    // sqlite: existing connection is already bound\n    await this.db.query('BEGIN', []);\n    this.started = true;\n  }\n\n  async query(sql: string, params: unknown[]): Promise<QueryResult> {\n    await this.ensureStarted();\n    return await this.activeDb.query(sql, params);\n  }\n\n  async commitIfStarted() {\n    if (this.completed) return;\n    if (!this.started) {\n      this.completed = true;\n      return;\n    }\n    await this.activeDb.query('COMMIT', []);\n    this.completed = true;\n  }\n\n  async rollbackIfStarted() {\n    if (this.completed) return;\n    if (!this.started) {\n      this.completed = true;\n      return;\n    }\n    await this.activeDb.query('ROLLBACK', []);\n    this.completed = true;\n  }\n\n  async release() {\n    try {\n      if (this.releaseFn) await this.releaseFn();\n    } finally {\n      this.txDb = undefined;\n      this.releaseFn = undefined;\n    }\n  }\n\n  async finishOnSuccess() {\n    try {\n      if (this.rollbackOnly) {\n        await this.rollbackIfStarted();\n        if (typeof this.rollbackError !== 'undefined') throw this.rollbackError;\n        throw new RollbackTransactionError();\n      }\n      await this.commitIfStarted();\n    } finally {\n      await this.release();\n    }\n  }\n\n  async finishOnError(err: unknown) {\n    try {\n      await this.rollbackIfStarted();\n    } finally {\n      await this.release();\n    }\n    if (isRollbackTransactionError(err)) {\n      throw unwrapRollbackCause(err);\n    }\n    throw err;\n  }\n}\n\nfunction enterTx(dbName: string, options?: TransactionOptions): { handle: TransactionHandle; store: TxStore; isNewStore: boolean } {\n  const { store, isNew } = getOrCreateStore();\n  const existing = store.txByDb.get(dbName);\n  if (existing) {\n    existing.depth++;\n    return { handle: new TransactionHandle(dbName, existing, false), store, isNewStore: isNew };\n  }\n  const { db } = SqlStackDB.getEntry(dbName);\n  const state = new TxState(dbName, db, options);\n  store.txByDb.set(dbName, state);\n  return { handle: new TransactionHandle(dbName, state, true), store, isNewStore: isNew };\n}\n\nasync function exitTx(dbName: string, store: TxStore) {\n  const state = store.txByDb.get(dbName);\n  if (!state) return;\n  state.depth = Math.max(0, state.depth - 1);\n  if (state.depth === 0) {\n    store.txByDb.delete(dbName);\n  }\n}\n\nexport function currentTransaction(db?: string): TransactionHandle | undefined {\n  const store = getStore();\n  if (!store) return undefined;\n  const resolved = SqlStackDB.getEntry(db).name;\n  const state = store.txByDb.get(resolved);\n  if (!state) return undefined;\n  return new TransactionHandle(resolved, state, false);\n}\n\nexport async function withTransaction<T>(fn: () => Promise<T>, options?: TransactionOptions): Promise<T> {\n  const resolved = SqlStackDB.getEntry(options?.db).name;\n  const { handle, store, isNewStore } = enterTx(resolved, options);\n\n  const run = async () => {\n    try {\n      const out = await fn();\n      await handle.finishOnSuccess();\n      return out;\n    } catch (err) {\n      await handle.finishOnError(err);\n      throw err;\n    } finally {\n      await exitTx(resolved, store);\n    }\n  };\n\n  return isNewStore ? await als.run(store, run) : await run();\n}\n\nexport type TransactionDecorator = {\n  (target: any, prop: string | symbol, desc: PropertyDescriptor): void;\n  (options?: TransactionOptions): (target: any, prop: string | symbol, desc: PropertyDescriptor) => void;\n};\n\nexport const transaction: TransactionDecorator = function (...args: any[]) {\n  // @transaction\n  if (args.length === 3 && typeof args[2]?.value === 'function') {\n    const [target, prop, desc] = args as [any, string | symbol, PropertyDescriptor];\n    wrapMethod(target, prop, desc, undefined);\n    return;\n  }\n  // @transaction() or @transaction({ ... })\n  const options: TransactionOptions | undefined = args.length > 0 ? args[0] : undefined;\n  return function (target: any, prop: string | symbol, desc: PropertyDescriptor) {\n    wrapMethod(target, prop, desc, options);\n  };\n} as any;\n\nfunction wrapMethod(_target: any, _prop: string | symbol, desc: PropertyDescriptor, options?: TransactionOptions) {\n  const original = desc.value;\n  desc.value = async function (...callArgs: any[]) {\n    return await withTransaction(() => original.apply(this, callArgs), options);\n  };\n}\n\nexport type ActiveTransaction = {\n  query(sql: string, params: unknown[]): Promise<QueryResult>;\n};\n\nexport function getActiveTransaction(dbName: string): ActiveTransaction | undefined {\n  const store = getStore();\n  return store?.txByDb.get(dbName);\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sqlstack",
-  "version": "1.0.20",
+  "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: