@m2k-5f/pgtx 1.0.4 → 1.1.0

package/README.md

@@ -139,6 +139,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 becomes NULL
+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: [T, ...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;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"}

package/dist/clauses/insert.clause.js

@@ -0,0 +1,34 @@
+"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]);
+        let text = `(${columns.join(', ')}) VALUES `;
+        let args = [];
+        const valuesText = this.inserts.map(values => {
+            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/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":"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"}

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/index.d.ts

@@ -4,7 +4,7 @@ import { identClause } from "./clauses/iden.caluse";
 import { Pool as PgtxPool } from "./pool";
 import { staticClause } from "./clauses/static.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.
      *

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,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"}

package/dist/index.js

@@ -7,7 +7,7 @@ const iden_caluse_1 = require("./clauses/iden.caluse");
 const pool_1 = require("./pool");
 const static_clause_1 = require("./clauses/static.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.
      *

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.4",
+  "version": "1.1.0",
   "description": "Lightweight, high-performance SQL toolkit for node-postgres",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -12,9 +12,17 @@
     "build": "tsc",
     "prepublishOnly": "npm run build"
   },
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/M2K-5F/pgtx.git"
+  },
   "keywords": ["sql", "postgres", "pg", "query-builder", "typescript", "transactions", "prepared-statements"],
   "author": "M2K-5F",
   "license": "MIT",
+  "homepage": "https://github.com/M2K-5F/pgtx",
+  "bugs": {
+    "url": "https://github.com/M2K-5F/pgtx/issues"
+  },
   "dependencies": {
     "pg": "^8.11.0"
   },