@m2k-5f/pgtx 1.1.0 → 1.2.0

package/README.md

@@ -7,7 +7,7 @@ Experience ORM-like convenience (auto-inserts, updates, recursive fragments) wit
 
 ## 🔥 Why Pgtx?
 
-*   **Zero-Cost Abstraction**: Only ~2% overhead compared to raw `pg.query`.
+*   **Zero-Cost Abstraction**: Only ~2% - 0% overhead compared to raw `pg.query`.
 *   **Structural Caching**: Uses `WeakMap` to cache SQL templates. Static parts are parsed only once.
 *   **Explicit Prepared Statements**: Create and reuse prepared statements with type safety
 *   **True Recursion**: Nest `sql.fragment` anywhere. Argument numbering ($1, $2) is managed automatically across all nesting levels.
@@ -46,8 +46,8 @@ The following results were measured during sequential execution of 10,000 comple
 
 | Tool | RPS | Avg. Query Time | Performance Overhead |
 | :--- | :---: | :---: | :---: |
-| **Native `pg.query`** | **~194** | **5.15 ms** | **0% (Baseline)** |
-| **Pgtx** | **~190** | **5.27 ms** | **~2.1%** |
+| **Native `pg.query`** | **~176** | **5.696 ms** | **0% (Baseline)** |
+| **Pgtx** | **~177** | **5.664 ms** | **-0.56%(zero-cost)** |
 | Typical Node.js ORM | **~58** | 12.5+ ms | > 150% |
 
 
@@ -76,10 +76,14 @@ await pool.begin(async (tx) => {
     await tx.query`UPDATE accounts SET balance = balance - 100 WHERE id = 1`;
     
     // Nested transaction (Savepoint)
-    await tx.savepoint('inventory', async (stx) => {
+    let err = await tx.savepoint('inventory', async (stx) => {
         await stx.query`UPDATE stock SET count = count - 1 WHERE item_id = ${42}`;
         if (outOfStock) throw new Error(); // Only 'inventory' rolls back
     });
+    if (err) {
+      // Handle error
+      // tx still active & can be commited
+    }
 });
 // Main transaction commits or rolls back based on callback success
 ```
@@ -171,7 +175,7 @@ await pool.query`
 `
 // SQL: UPDATE users SET name = $1, deleted_at = $2 WHERE id = 1
 
-// Arrays: undefined becomes NULL
+// Arrays: undefined throw
 sql.array([1, undefined, 3]) // ❌ TypeError(`Array item at index 1 is undefined`)
 
 // Empty arrays throw (use [null] for NULL result)

package/dist/clauses/insert.clause.d.ts

@@ -5,5 +5,5 @@ export declare class InsertClause<T extends Record<string, any>> extends Clause
     constructor(inserts: T[]);
     map(argCounter: number): CompiledSqlQuery;
 }
-export declare function insertClause<T extends Record<string, any>>(...objects: [T, ...NoInfer<T>[]]): InsertClause<T>;
+export declare function insertClause<T extends Record<string, any>>(...objects: NoInfer<T>[]): InsertClause<T>;
 //# sourceMappingURL=insert.clause.d.ts.map

package/dist/clauses/insert.clause.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"insert.clause.d.ts","sourceRoot":"","sources":["../../src/clauses/insert.clause.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE5C,qBAAa,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAE,SAAQ,MAAM;IAE/D,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE;gBAAZ,OAAO,EAAE,CAAC,EAAE;IAGhB,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB;CA2BrD;AAED,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,mBAE3F"}
+{"version":3,"file":"insert.clause.d.ts","sourceRoot":"","sources":["../../src/clauses/insert.clause.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE5C,qBAAa,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAE,SAAQ,MAAM;IAE/D,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE;gBAAZ,OAAO,EAAE,CAAC,EAAE;IAGhB,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB;CAgCrD;AAED,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,mBAEnF"}

package/dist/clauses/insert.clause.js

@@ -14,9 +14,14 @@ class InsertClause extends base_clause_1.Clause {
                 'Provide at least one object with data.');
         }
         const columns = Object.keys(this.inserts[0]);
+        const columnsCount = columns.length;
         let text = `(${columns.join(', ')}) VALUES `;
         let args = [];
         const valuesText = this.inserts.map(values => {
+            if (Object.keys(values).length !== columnsCount)
+                throw new Error(`
+                all rows must have the same columns
+            `);
             return `(${Object.values(values).map(value => {
                 if (value === undefined)
                     return "DEFAULT";

package/dist/clauses/literal.clause.d.ts

@@ -0,0 +1,9 @@
+import { Clause } from "./base.clause";
+import { CompiledSqlQuery } from "../utils";
+export declare class LiteralClause<T extends string> extends Clause {
+    readonly value: T;
+    constructor(value: T);
+    map(argCounter: number): CompiledSqlQuery;
+}
+export declare function literalClause<T extends string>(value: T): LiteralClause<T>;
+//# sourceMappingURL=literal.clause.d.ts.map

package/dist/clauses/literal.clause.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"literal.clause.d.ts","sourceRoot":"","sources":["../../src/clauses/literal.clause.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAC,MAAM,eAAe,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE5C,qBAAa,aAAa,CAAC,CAAC,SAAS,MAAM,CAAE,SAAQ,MAAM;IAEnD,QAAQ,CAAC,KAAK,EAAE,CAAC;gBAAR,KAAK,EAAE,CAAC;IAKZ,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB;CAMrD;AAGD,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAE1E"}

package/dist/clauses/literal.clause.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LiteralClause = void 0;
+exports.literalClause = literalClause;
+const base_clause_1 = require("./base.clause");
+class LiteralClause extends base_clause_1.Clause {
+    constructor(value) {
+        super();
+        this.value = value;
+    }
+    map(argCounter) {
+        if (this.value === undefined) {
+            throw new TypeError(`Query parameter undefined at position ${argCounter}`);
+        }
+        return { text: this.value, args: [], argCounter };
+    }
+}
+exports.LiteralClause = LiteralClause;
+function literalClause(value) {
+    return new LiteralClause(value);
+}

package/dist/clauses/update.clause.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"update.clause.d.ts","sourceRoot":"","sources":["../../src/clauses/update.clause.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE5C,qBAAa,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAE,SAAQ,MAAM;IAE/D,QAAQ,CAAC,SAAS,EAAE,CAAC;gBAAZ,SAAS,EAAE,CAAC;IAGhB,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB;CAcrD;AAED,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC,mBAEpE"}
+{"version":3,"file":"update.clause.d.ts","sourceRoot":"","sources":["../../src/clauses/update.clause.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE5C,qBAAa,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAE,SAAQ,MAAM;IAE/D,QAAQ,CAAC,SAAS,EAAE,CAAC;gBAAZ,SAAS,EAAE,CAAC;IAGhB,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB;CAcrD;AAED,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC,mBAEpE"}

package/dist/connection.d.ts

@@ -26,7 +26,7 @@ export declare class Connection {
      * Releases the connection back to the pool.
      * The connection cannot be used after this call.
      */
-    release(): void;
+    release(): Promise<void>;
     private checkActive;
     /**
      * Executes a tagged SQL query using structural caching.

package/dist/connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,IAAI,CAAA;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAK3C;;;GAGG;AACH,qBAAa,UAAU;IAIf,OAAO,CAAC,QAAQ,CAAC,MAAM;IAH3B,OAAO,CAAC,UAAU,CAAiB;gBAGd,MAAM,EAAE,UAAU;IAGvC;;OAEG;IACH,IAAW,QAAQ,IAAI,OAAO,CAE7B;IAED;;;;;;;OAOG;IACU,OAAO,CAAC,OAAO,SAAS,cAAc,GAAG,GAAG,EAAE,OAAO,SAAS,GAAG,EAAE,GAAG,GAAG,EAAE,EACpF,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GACpB,OAAO,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAoB/C;;;OAGG;IACI,OAAO,IAAI,IAAI;IAMtB,OAAO,CAAC,WAAW;IAMnB;;;;;;OAMG;IACU,KAAK,CAAC,CAAC,SAAS,cAAc,GAAG,GAAG,EAAE,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAUjH;;;;;;;;OAQG;IACU,KAAK,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAmB/E"}
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,IAAI,CAAA;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAK3C;;;GAGG;AACH,qBAAa,UAAU;IAIf,OAAO,CAAC,QAAQ,CAAC,MAAM;IAH3B,OAAO,CAAC,UAAU,CAAiB;gBAGd,MAAM,EAAE,UAAU;IAGvC;;OAEG;IACH,IAAW,QAAQ,IAAI,OAAO,CAE7B;IAED;;;;;;;OAOG;IACU,OAAO,CAAC,OAAO,SAAS,cAAc,GAAG,GAAG,EAAE,OAAO,SAAS,GAAG,EAAE,GAAG,GAAG,EAAE,EACpF,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GACpB,OAAO,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAoB/C;;;OAGG;IACU,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAMrC,OAAO,CAAC,WAAW;IAMnB;;;;;;OAMG;IACU,KAAK,CAAC,CAAC,SAAS,cAAc,GAAG,GAAG,EAAE,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAUjH;;;;;;;;OAQG;IACU,KAAK,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAmB/E"}

package/dist/connection.js

@@ -48,7 +48,7 @@ class Connection {
      * Releases the connection back to the pool.
      * The connection cannot be used after this call.
      */
-    release() {
+    async release() {
         if (this.isReleased)
             return;
         this.isReleased = true;

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { arrayClause } from "./clauses/array.clause";
 import { fragmentClause } from "./clauses/fragment.clause";
 import { identClause } from "./clauses/iden.caluse";
 import { Pool as PgtxPool } from "./pool";
-import { staticClause } from "./clauses/static.clause";
+import { literalClause } from "./clauses/literal.clause";
 import { updateClause } from "./clauses/update.clause";
 import { insertClause } from "./clauses/insert.clause";
 /**
@@ -51,7 +51,7 @@ export declare const sql: {
      * sql.literal('DESC')
      * // Result: DESC
      */
-    literal: typeof staticClause;
+    literal: typeof literalClause;
     /**
      * Creates a reusable, recursive SQL fragment.
      * Fragments can be nested within each other; argument numbering is handled automatically.

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAEvD;;;GAGG;AACH,eAAO,MAAM,GAAG;IACZ;;;;;;;;;;;OAWG;;IAGH;;;;;;OAMG;;IAGH;;;;;;;;;;OAUG;;IAGH;;;;;;;OAOG;;IAGH;;;;;;;;OAQG;;IAGH;;;;;;;;;;;;;;;;;;;OAmBG;;CAEN,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,IAAI,iBAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAEvD;;;GAGG;AACH,eAAO,MAAM,GAAG;IACZ;;;;;;;;;;;OAWG;;IAGH;;;;;;OAMG;;IAGH;;;;;;;;;;OAUG;;IAGH;;;;;;;OAOG;;IAGH;;;;;;;;OAQG;;IAGH;;;;;;;;;;;;;;;;;;;OAmBG;;CAEN,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,IAAI,iBAAW,CAAA"}

package/dist/index.js

@@ -5,7 +5,7 @@ const array_clause_1 = require("./clauses/array.clause");
 const fragment_clause_1 = require("./clauses/fragment.clause");
 const iden_caluse_1 = require("./clauses/iden.caluse");
 const pool_1 = require("./pool");
-const static_clause_1 = require("./clauses/static.clause");
+const literal_clause_1 = require("./clauses/literal.clause");
 const update_clause_1 = require("./clauses/update.clause");
 const insert_clause_1 = require("./clauses/insert.clause");
 /**
@@ -54,7 +54,7 @@ exports.sql = {
      * sql.literal('DESC')
      * // Result: DESC
      */
-    literal: static_clause_1.staticClause,
+    literal: literal_clause_1.literalClause,
     /**
      * Creates a reusable, recursive SQL fragment.
      * Fragments can be nested within each other; argument numbering is handled automatically.

package/dist/transaction.d.ts

@@ -35,6 +35,6 @@ export declare class Transaction {
      *   if (error) throw new Error(); // Only this insert rolls back
      * });
      */
-    savepoint(name: string, callback: (tx: Transaction) => Promise<void>): Promise<void>;
+    savepoint(name: string, callback: (tx: Transaction) => Promise<void>): Promise<Error | null>;
 }
 //# sourceMappingURL=transaction.d.ts.map

package/dist/transaction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,IAAI,CAAA;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAIzC;;;GAGG;AACH,qBAAa,WAAW;IAIhB,QAAQ,CAAC,IAAI,EAAE,UAAU;IAH7B,OAAO,CAAC,UAAU,CAAiB;gBAGtB,IAAI,EAAE,UAAU;IAG7B;;OAEG;IACH,IAAW,QAAQ,IAAI,OAAO,CAE7B;IAED,OAAO,CAAC,WAAW;IAMnB;;OAEG;IACU,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAOpC;;OAEG;IACU,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtC;;OAEG;IACU,KAAK,CAAC,CAAC,SAAS,cAAc,GAAG,GAAG,EAAE,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAKjH;;;;;;;;;OASG;IACU,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAcpG"}
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,IAAI,CAAA;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAIzC;;;GAGG;AACH,qBAAa,WAAW;IAIhB,QAAQ,CAAC,IAAI,EAAE,UAAU;IAH7B,OAAO,CAAC,UAAU,CAAiB;gBAGtB,IAAI,EAAE,UAAU;IAG7B;;OAEG;IACH,IAAW,QAAQ,IAAI,OAAO,CAE7B;IAED,OAAO,CAAC,WAAW;IAMnB;;OAEG;IACU,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAOpC;;OAEG;IACU,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtC;;OAEG;IACU,KAAK,CAAC,CAAC,SAAS,cAAc,GAAG,GAAG,EAAE,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAKjH;;;;;;;;;OASG;IACU,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;CAe5G"}

package/dist/transaction.js

@@ -61,10 +61,11 @@ class Transaction {
         try {
             await callback(this);
             await this.conn.query `RELEASE SAVEPOINT ${(0, iden_caluse_1.identClause)(name)}`;
+            return null;
         }
         catch (err) {
             await this.conn.query `ROLLBACK TO SAVEPOINT ${(0, iden_caluse_1.identClause)(name)}`;
-            throw err;
+            return err instanceof Error ? err : new Error(String(err));
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m2k-5f/pgtx", 
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Lightweight, high-performance SQL toolkit for node-postgres",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",