sqlstack 1.0.17 → 1.0.18

package/readme.md

@@ -262,56 +262,320 @@ await repo.listByIds({ ids });
 - `null` → SQL `NULL`
 - `undefined` → throws an error; always provide a value or omit the parameter
 
-### Automatic NULL Binding with `@MissingAsNull`
+### :update() Syntax for Partial Updates
 
-By default, missing or undefined named parameters throw an error. Use `@MissingAsNull` to automatically bind missing parameters as `NULL` instead, enabling partial updates with `COALESCE`/`IFNULL`:
+The `:update()` syntax simplifies UPDATE statements by automatically generating SET clauses. It supports both parameterized columns and literal SQL expressions, making partial updates easy without needing `COALESCE` or `IFNULL`.
+
+**Key Features:**
+- Automatically generates `SET` keyword (don't write it yourself)
+- Literal expressions: `col = datetime('now')` → always included
+- Parameterized columns: `col` → only included if defined in args
+- Mixed usage: combine literals and parameterized columns
+
+**Basic Usage:**
+
+```sql
+-- updateInvoice.sql
+UPDATE invoices
+  :update(invoice_date, due_date, subtotal_cents)
+WHERE id = :id
+```
 
 ```ts
-import { QueryBinder, MissingAsNull, Query, SqlStackError } from "sqlstack";
+await repo.updateInvoice({ 
+  invoice_date: '2024-01-01', 
+  id: 1 
+});
+// Generates: UPDATE invoices SET invoice_date = ? WHERE id = ?
+// due_date and subtotal_cents are skipped (undefined)
+```
 
-@QueryBinder()
-class UsersRepo {
-  @MissingAsNull()
-  @Query({
-    sql: `
-      UPDATE users
-      SET name = COALESCE(:name, name),
-          email = COALESCE(:email, email),
-          status = COALESCE(:status, status)
+**Literal SQL Expressions:**
+
+Use `=` to include literal SQL expressions that are always included:
+
+```sql
+UPDATE invoices
+  :update(updated_at = datetime('now'), invoice_date, due_date)
       WHERE id = :id
-    `
-  })
-  async updateUserPartial(_a: { id: string; name?: string; email?: string; status?: string }): Promise<any> {
-    throw new SqlStackError("replaced");
-  }
-}
 ```
 
-Call with partial arguments:
 ```ts
-await repo.updateUserPartial({ id: "u1", name: "Alice Updated" });
-// Only updates name; email and status keep their old values via COALESCE
+await repo.updateInvoice({ 
+  invoice_date: '2024-01-01', 
+  id: 1 
+});
+// Generates: UPDATE invoices SET updated_at = datetime('now'), invoice_date = ? WHERE id = ?
 ```
 
-**Optional: Require Specific Parameters**
+**Mixed Literal and Parameterized:**
 
-Use `@MissingAsNull({ require: ['id'] })` to mark certain parameters as required:
+```sql
+UPDATE invoices
+  :update(
+    updated_at = datetime('now'),
+    invoice_date,
+    due_date,
+    status = 'active'
+  )
+WHERE id = :id
+```
 
 ```ts
-@MissingAsNull({ require: ['id'] })
-@Query({
-  sql: `UPDATE users SET name = COALESCE(:name, name) WHERE id = :id`
-})
-async updateUser(_a: { id: string; name?: string }): Promise<any> {
-  throw new SqlStackError("replaced");
-}
+await repo.updateInvoice({ 
+  invoice_date: '2024-01-01', 
+  due_date: '2024-01-15',
+  id: 1 
+});
+// Generates: UPDATE invoices SET updated_at = datetime('now'), invoice_date = ?, due_date = ?, status = 'active' WHERE id = ?
 ```
 
-If `id` is missing or undefined, an error is thrown. Other parameters default to `NULL`.
+**Notes:**
+- `:update()` only works with named parameters (not positional)
+- Literal expressions are always included
+- Parameterized columns are only included if defined and not `undefined`
+- If all parameterized columns are undefined (and no literals), throws an error
+- Case-insensitive: `:update`, `:UPDATE`, `:Update` all work
 
-**Note:** `@MissingAsNull` only applies to named parameters. Positional parameters (`:arg1`, `:arg2`, etc.) ignore the decorator.
+### :insert() Syntax for INSERT Statements
 
----
+The `:insert()` syntax simplifies INSERT statements by automatically generating both the column list and VALUES clause. It supports both parameterized columns and literal SQL expressions, making INSERT statements much more concise.
+
+**Key Features:**
+- Automatically generates column list `(col1, col2, ...)` and VALUES clause `VALUES (?, ?, ...)`
+- Literal expressions: `col = datetime('now')` → column name and literal value included
+- Parameterized columns: `col` → only included if defined in args
+- Mixed usage: combine literals and parameterized columns
+
+**Basic Usage:**
+
+```sql
+-- createInvoice.sql
+INSERT INTO invoices :insert(case_id, invoice_number, invoice_date, due_date)
+```
+
+```ts
+await repo.createInvoice({ 
+  case_id: 1,
+  invoice_number: 'INV-001', 
+  invoice_date: '2024-01-01',
+  due_date: '2024-01-15'
+});
+// Generates: INSERT INTO invoices (case_id, invoice_number, invoice_date, due_date) VALUES (?, ?, ?, ?)
+// Params: [1, 'INV-001', '2024-01-01', '2024-01-15']
+```
+
+**With Undefined Columns:**
+
+```sql
+INSERT INTO invoices :insert(case_id, invoice_number, invoice_date, due_date)
+```
+
+```ts
+await repo.createInvoice({ 
+  case_id: 1,
+  invoice_number: 'INV-001'
+});
+// Generates: INSERT INTO invoices (case_id, invoice_number) VALUES (?, ?)
+// invoice_date and due_date are skipped (undefined)
+```
+
+**Literal SQL Expressions:**
+
+Use `=` to include literal SQL expressions that are always included:
+
+```sql
+INSERT INTO invoices :insert(created_at = datetime('now'), case_id, invoice_number)
+```
+
+```ts
+await repo.createInvoice({ 
+  case_id: 1,
+  invoice_number: 'INV-001'
+});
+// Generates: INSERT INTO invoices (created_at, case_id, invoice_number) VALUES (datetime('now'), ?, ?)
+// Params: [1, 'INV-001']
+```
+
+**Mixed Literal and Parameterized:**
+
+```sql
+INSERT INTO invoices :insert(
+  created_at = datetime('now'),
+  case_id,
+  invoice_number,
+  status = 'draft'
+)
+```
+
+```ts
+await repo.createInvoice({ 
+  case_id: 1,
+  invoice_number: 'INV-001'
+});
+// Generates: INSERT INTO invoices (created_at, case_id, invoice_number, status) VALUES (datetime('now'), ?, ?, 'draft')
+// Params: [1, 'INV-001']
+```
+
+**Notes:**
+- `:insert()` only works with named parameters (not positional)
+- Literal expressions are always included (both column name and value)
+- Parameterized columns are only included if defined and not `undefined`
+- If all parameterized columns are undefined (and no literals), throws an error
+- Case-insensitive: `:insert`, `:INSERT`, `:Insert` all work
+
+### :filter() Syntax for WHERE/HAVING Clauses
+
+The `:filter()` syntax simplifies WHERE and HAVING clauses by automatically generating conditions. It supports simple column names (equality), literal comparisons, and parameterized comparisons, making dynamic filtering much easier.
+
+**Key Features:**
+- Simple column names → equality: `name` → `name = ?`
+- Literal comparisons → included as-is: `age > 30` → `age > 30`
+- Parameterized comparisons → bind parameters: `age > :min_age` → `age > ?`
+- Mixed usage: combine all three types
+- Works in both WHERE and HAVING clauses
+- Conditions are joined with `AND`
+
+**Basic Usage:**
+
+```sql
+-- findUsers.sql
+SELECT * FROM users WHERE :filter(name, age)
+```
+
+```ts
+await repo.findUsers({ name: 'John', age: 30 });
+// Generates: SELECT * FROM users WHERE name = ? AND age = ?
+// Params: ['John', 30]
+```
+
+**With Some Undefined Columns:**
+
+```sql
+SELECT * FROM users WHERE :filter(name, age, status)
+```
+
+```ts
+await repo.findUsers({ name: 'John' });
+// Generates: SELECT * FROM users WHERE name = ?
+// age and status are skipped (undefined)
+```
+
+**Literal Comparisons:**
+
+```sql
+SELECT * FROM users WHERE :filter(age > 30, status = 'active')
+```
+
+```ts
+await repo.findUsers({});
+// Generates: SELECT * FROM users WHERE age > 30 AND status = 'active'
+// Params: []
+```
+
+**Parameterized Comparisons:**
+
+```sql
+SELECT * FROM users WHERE :filter(age > :min_age, name LIKE :search)
+```
+
+```ts
+await repo.findUsers({ min_age: 30, search: '%John%' });
+// Generates: SELECT * FROM users WHERE age > ? AND name LIKE ?
+// Params: [30, '%John%']
+```
+
+**Mixed Usage:**
+
+```sql
+SELECT * FROM users WHERE :filter(name, age > :min_age, status = 'active')
+```
+
+```ts
+await repo.findUsers({ name: 'John', min_age: 30 });
+// Generates: SELECT * FROM users WHERE name = ? AND age > ? AND status = 'active'
+// Params: ['John', 30]
+```
+
+**With Array Parameters (IN clause):**
+
+```sql
+SELECT * FROM users WHERE :filter(id IN (:ids))
+```
+
+```ts
+await repo.findUsers({ ids: [1, 2, 3] });
+// Generates: SELECT * FROM users WHERE id IN (?, ?, ?)
+// Params: [1, 2, 3]
+```
+
+**With :or() Expansion:**
+
+The `:or()` syntax expands array parameters into multiple OR conditions:
+
+```sql
+SELECT * FROM users WHERE :filter(name = :or(:names), age > :min_age)
+```
+
+```ts
+await repo.findUsers({ names: ['John', 'Jane', 'Bob'], min_age: 30 });
+// Generates: SELECT * FROM users WHERE (name = ? OR name = ? OR name = ?) AND age > ?
+// Params: ['John', 'Jane', 'Bob', 30]
+```
+
+**Complex :or() Usage:**
+
+```sql
+SELECT * FROM users WHERE :filter(
+  (name = :or(:names)),
+  age > :min_age,
+  status = 'active',
+  (department = :or(:depts) OR role = :or(:roles))
+)
+```
+
+```ts
+await repo.findUsers({ 
+  names: ['John', 'Jane'], 
+  min_age: 25, 
+  depts: ['Engineering'], 
+  roles: ['Manager'] 
+});
+// Generates: SELECT * FROM users WHERE (name = ? OR name = ?) AND age > ? AND status = 'active' AND (department = ? OR role = ?)
+// Params: ['John', 'Jane', 25, 'Engineering', 'Manager']
+```
+
+**HAVING Clause:**
+
+```sql
+SELECT department, COUNT(*) as count 
+FROM employees 
+GROUP BY department 
+HAVING :filter(count > :min_count, department = 'Sales')
+```
+
+```ts
+await repo.findDepartments({ min_count: 10 });
+// Generates: SELECT department, COUNT(*) as count FROM employees GROUP BY department HAVING count > ? AND department = 'Sales'
+// Params: [10]
+```
+
+**Supported Operators:**
+
+- Comparison: `=`, `!=`, `<>`, `>`, `<`, `>=`, `<=`
+- Pattern matching: `LIKE`
+- Membership: `IN`
+- Range: `BETWEEN`
+- Null checks: `IS NULL`, `IS NOT NULL`
+
+**Notes:**
+- `:filter()` only works with named parameters (not positional)
+- Literal expressions are always included
+- Parameterized conditions are only included if the parameter is defined and not `undefined`
+- If all parameterized conditions are undefined (and no literals), throws an error
+- Case-insensitive: `:filter`, `:FILTER`, `:Filter` all work
+- `:or()` expands arrays into multiple OR conditions
+- Operators inside string literals are not treated as operators (e.g., `name = 'value > test'`)
 
 ## SQL File Resolution