@m2k-5f/pgtx 1.0.5 → 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
 ```
@@ -139,6 +143,44 @@ await pool.query`UPDATE users SET ${sql.update(data)} WHERE id = ${1}`
 // SQL: UPDATE users SET status = $1, last_login = $2 WHERE id = $3
 ```
 
+## 🔄 Null & Undefined Handling
+
+Pgtx treats `null` and `undefined` differently to match SQL semantics and JavaScript expectations:
+
+| Value | In INSERT | In UPDATE | In VALUES/Parameters | In Arrays |
+|-------|-----------|-----------|----------------------|-----------|
+| `null` | `NULL` | `NULL` | `NULL` | `NULL` |
+| `undefined` | `DEFAULT` | Field skipped | Error | Error |
+
+### Examples
+
+```typescript
+// INSERT: undefined becomes DEFAULT
+await pool.query`
+  INSERT INTO users ${sql.insert({ 
+    name: 'Alice', 
+    age: undefined,  // -> DEFAULT
+    email: null      // -> NULL
+  })}
+`
+// SQL: INSERT INTO users (name, age, email) VALUES ($1, DEFAULT, $2)
+
+// UPDATE: undefined fields are skipped
+await pool.query`
+  UPDATE users SET ${sql.update({ 
+    name: 'Bob',
+    age: undefined,  // skipped - age remains unchanged
+    deleted_at: null // explicitly set to NULL
+  })} WHERE id = 1
+`
+// SQL: UPDATE users SET name = $1, deleted_at = $2 WHERE id = 1
+
+// Arrays: undefined throw
+sql.array([1, undefined, 3]) // ❌ TypeError(`Array item at index 1 is undefined`)
+
+// Empty arrays throw (use [null] for NULL result)
+sql.array([]) // ❌ Error: Array clause is empty. Use sql.array([null])...
+```
 
 ## 🛡️ Security
 *    **SQL Injection**: Automatically uses native placeholders ($1, $2) for all values.

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

@@ -1 +1 @@
-{"version":3,"file":"array.clause.d.ts","sourceRoot":"","sources":["../../src/clauses/array.clause.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE5C,qBAAa,WAAY,SAAQ,MAAM;IAE/B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBADT,KAAK,EAAE,GAAG,EAAE,EACZ,SAAS,GAAE,MAAa;IAGpC,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB;CAmBrD;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,SAAS,GAAE,MAAa,GAAG,WAAW,CAE/E"}
+{"version":3,"file":"array.clause.d.ts","sourceRoot":"","sources":["../../src/clauses/array.clause.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE5C,qBAAa,WAAY,SAAQ,MAAM;IAE/B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBADT,KAAK,EAAE,GAAG,EAAE,EACZ,SAAS,GAAE,MAAa;IAGpC,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB;CAyBrD;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,SAAS,GAAE,MAAa,GAAG,WAAW,CAE/E"}

package/dist/clauses/array.clause.js

@@ -11,9 +11,12 @@ class ArrayClause extends base_clause_1.Clause {
     }
     map(argCounter) {
         if (this.array.length === 0)
-            return { text: 'NULL', args: [], argCounter };
+            throw new Error('Array clause is empty.\n Use sql.array([null]) if you want no results, or check your data.');
         const args = [];
-        const text = `${this.array.map(value => {
+        const text = `${this.array.map((value, index) => {
+            if (value === undefined) {
+                throw new TypeError(`Array item at index ${index} is undefined`);
+            }
             if (value instanceof base_clause_1.Clause) {
                 const result = value.map(argCounter);
                 args.push(...result.args);

package/dist/clauses/iden.caluse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"iden.caluse.d.ts","sourceRoot":"","sources":["../../src/clauses/iden.caluse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE5C,qBAAa,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAE,SAAQ,MAAM;IAEtD,QAAQ,CAAC,KAAK,EAAE,CAAC;gBAAR,KAAK,EAAE,CAAC;IAGZ,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB;CAMrD;AAED,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAAE,aAAa,EAAE,CAAC,uBAE7D"}
+{"version":3,"file":"iden.caluse.d.ts","sourceRoot":"","sources":["../../src/clauses/iden.caluse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE5C,qBAAa,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAE,SAAQ,MAAM;IAEtD,QAAQ,CAAC,KAAK,EAAE,CAAC;gBAAR,KAAK,EAAE,CAAC;IAGZ,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB;CASrD;AAED,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAAE,aAAa,EAAE,CAAC,uBAE7D"}

package/dist/clauses/iden.caluse.js

@@ -9,6 +9,9 @@ class IdentifierClause extends base_clause_1.Clause {
         this.value = value;
     }
     map(argCounter) {
+        if (this.value === undefined) {
+            throw new TypeError(`Query parameter undefined at position ${argCounter}`);
+        }
         const text = `"${this.value}"`;
         const args = [];
         return { text, args, argCounter };

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

@@ -0,0 +1,9 @@
+import { Clause } from "./base.clause";
+import { CompiledSqlQuery } from "../utils";
+export declare class InsertClause<T extends Record<string, any>> extends Clause {
+    readonly inserts: T[];
+    constructor(inserts: T[]);
+    map(argCounter: number): CompiledSqlQuery;
+}
+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

@@ -0,0 +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;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

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InsertClause = void 0;
+exports.insertClause = insertClause;
+const base_clause_1 = require("./base.clause");
+class InsertClause extends base_clause_1.Clause {
+    constructor(inserts) {
+        super();
+        this.inserts = inserts;
+    }
+    map(argCounter) {
+        if (this.inserts.length === 0) {
+            throw new Error('Insert clause has no rows to insert.\n' +
+                '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";
+                args.push(value);
+                return `$${argCounter++}`;
+            }).join(", ")})`;
+        }).join(", ");
+        text += valuesText;
+        return { text, args, argCounter };
+    }
+}
+exports.InsertClause = InsertClause;
+function insertClause(...objects) {
+    return new InsertClause(objects);
+}

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/static.clause.d.ts.map

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

package/dist/clauses/static.clause.js

@@ -9,6 +9,9 @@ class StaticClause extends base_clause_1.Clause {
         this.value = value;
     }
     map(argCounter) {
+        if (this.value === undefined) {
+            throw new TypeError(`Query parameter undefined at position ${argCounter}`);
+        }
         return { text: this.value, args: [], argCounter };
     }
 }

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

@@ -2,9 +2,8 @@ import { Clause } from "./base.clause";
 import { CompiledSqlQuery } from "../utils";
 export declare class UpdateClause<T extends Record<string, any>> extends Clause {
     readonly updateMap: T;
-    readonly columns?: (keyof T)[] | undefined;
-    constructor(updateMap: T, columns?: (keyof T)[] | undefined);
+    constructor(updateMap: T);
     map(argCounter: number): CompiledSqlQuery;
 }
-export declare function updateClause<T extends Record<string, any>>(object: T, ...updateColumns: (keyof T)[]): UpdateClause<T>;
+export declare function updateClause<T extends Record<string, any>>(object: T): UpdateClause<T>;
 //# sourceMappingURL=update.clause.d.ts.map

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;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE;gBADrB,SAAS,EAAE,CAAC,EACZ,OAAO,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,YAAA;IAGzB,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB;CAerD;AAED,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,GAAG,aAAa,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,YAAY,CAAC,CAAC,CAAC,CAErH"}
+{"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/clauses/update.clause.js

@@ -4,23 +4,23 @@ exports.UpdateClause = void 0;
 exports.updateClause = updateClause;
 const base_clause_1 = require("./base.clause");
 class UpdateClause extends base_clause_1.Clause {
-    constructor(updateMap, columns) {
+    constructor(updateMap) {
         super();
         this.updateMap = updateMap;
-        this.columns = columns;
     }
     map(argCounter) {
-        const columns = this.columns || Object.keys(this.updateMap);
         const args = [];
-        const text = columns
-            .map((key) => {
-            args.push(this.updateMap[key]);
-            return `${key.toString()} = $${argCounter++}`;
+        const entries = Object.entries(this.updateMap).filter(([_, value]) => value !== undefined);
+        if (entries.length === 0)
+            throw new Error('Update clause has no data to update. All values are `undefined`');
+        const text = entries.map(([key, value]) => {
+            args.push(value);
+            return `${key} = $${argCounter++}`;
         }).join(', ');
         return { text, args, argCounter };
     }
 }
 exports.UpdateClause = UpdateClause;
-function updateClause(object, ...updateColumns) {
-    return new UpdateClause(object, updateColumns.length > 0 ? updateColumns : undefined);
+function updateClause(object) {
+    return new UpdateClause(object);
 }

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,9 +2,9 @@ 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 { valueClause } from "./clauses/values.clause";
+import { insertClause } from "./clauses/insert.clause";
 /**
  * Core SQL tagging utility for Pgtx.
  * Provides type-safe helpers for building dynamic queries with recursive support.
@@ -22,7 +22,7 @@ export declare const sql: {
      * sql.insert([{ id: 1 }, { id: 2 }])
      * // Result: (id) VALUES ($1), ($2)
      */
-    insert: typeof valueClause;
+    insert: typeof insertClause;
     /**
      * Generates a SET clause for UPDATE queries from a JavaScript object.
      *
@@ -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,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD;;;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,9 +5,9 @@ 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 values_clause_1 = require("./clauses/values.clause");
+const insert_clause_1 = require("./clauses/insert.clause");
 /**
  * Core SQL tagging utility for Pgtx.
  * Provides type-safe helpers for building dynamic queries with recursive support.
@@ -25,7 +25,7 @@ exports.sql = {
      * sql.insert([{ id: 1 }, { id: 2 }])
      * // Result: (id) VALUES ($1), ($2)
      */
-    insert: values_clause_1.valueClause,
+    insert: insert_clause_1.insertClause,
     /**
      * Generates a SET clause for UPDATE queries from a JavaScript object.
      *
@@ -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/dist/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,gBAAgB,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,UAAU,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,oBAAoB,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,gBAAgB,CAyBrH"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,gBAAgB,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,UAAU,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,oBAAoB,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,gBAAgB,CAgCrH"}

package/dist/utils.js

@@ -18,6 +18,10 @@ function compileSqlTemplate(strings, values, argCounter) {
             args.push(...result.args);
         }
         else {
+            if (value === undefined) {
+                throw new TypeError(`Query parameter at position ${argCounter} is undefined. 
+                    Use null if you want NULL in SQL, or ensure the value is defined.`);
+            }
             args.push(value);
             text += `$${argCounter}`;
             argCounter++;

package/package.json

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