sqlstack 1.0.19 → 1.0.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sqlstack",
-  "version": "1.0.19",
+  "version": "1.0.20",
   "description": "",
   "license": "ISC",
   "author": "",

package/readme.md

@@ -199,46 +199,89 @@ sqlstack adds a small set of macros that expand into standard SQL, so you keep f
 #### `:insert(...)`
 
 ```sql
--- invoices/createInvoice.sql
-INSERT INTO invoices :insert(case_id, invoice_number, invoice_date, due_date, status = 'draft');
+-- posts/createPost.sql
+INSERT INTO posts :insert(id, author_id, title, body, status = 'published');
 ```
 
 ```ts
-await repo.createInvoice({
-  case_id: 1,
-  invoice_number: "INV-001",
-  invoice_date: "2024-01-01",
-  // due_date: undefined
+await repo.createPost({
+  id: 'post_1',
+  author_id: 'user_1',
+  title: 'Hello world',
+  body: 'First post!',
+  // status: undefined → defaults to 'published' from SQL literal
 });
 ```
 
 ```sql
 -- expands to
-INSERT INTO invoices (case_id, invoice_number, invoice_date, status)
-VALUES (?, ?, ?, 'draft');
+INSERT INTO posts (id, author_id, title, body, status)
+VALUES (?, ?, ?, ?, 'published');
 ```
 
+**Additional behaviors and rules**
+
+- Columns whose values are `undefined` are skipped; at least one non-literal column must be defined or a literal must be present.
+- Pure literal expressions (e.g. `created_at = now()`) are allowed and included even with no params.
+- `null` values are allowed and are bound as `NULL`.
+- Column order in the generated `INSERT` follows the order listed in `:insert(...)`, regardless of object key order.
+- `:insert()` only works with **named parameters**; using positional args throws.
+
+#### `:batch_insert(...)`
+
+Use `:batch_insert(...)` to build an efficient multi-row `VALUES` clause from one or more array arguments (plus optional scalars):
+
+```sql
+-- comments/createComments.sql
+INSERT INTO comments (post_id, author_id, body)
+:batch_insert(post_id, comment.author_id, comment.body);
+```
+
+```ts
+await repo.createComments({
+  post_id: 'post_1',
+  comment: [
+    { author_id: 'user_1', body: 'Nice post!' },
+    { author_id: 'user_2', body: 'Subscribed.' },
+  ],
+});
+```
+
+```sql
+-- expands (MySQL/SQLite)
+INSERT INTO comments (post_id, author_id, body)
+VALUES (?, ?, ?), (?, ?, ?);
+
+-- expands (Postgres)
+INSERT INTO comments (post_id, author_id, body)
+VALUES ($1, $2, $3), ($4, $5, $6);
+```
+
+- At least one argument must resolve to an array; all array arguments must have the same length and be non-empty.
+- Arguments can be scalars (reused for every row) or dot-paths into nested objects/arrays (e.g. `comment.body`, `root.ids`).
+- `:batch_insert()` only works with **named parameters**, not positional ones.
+
 #### `:update(...)`
 
 ```sql
--- invoices/updateInvoice.sql
-UPDATE invoices
-  :update(updated_at = now(), invoice_date, due_date)
+-- posts/updatePost.sql
+UPDATE posts
+  :update(updated_at = now(), title, body)
 WHERE id = :id;
 ```
 
 ```ts
-await repo.updateInvoice({
-  id: 1,
-  invoice_date: "2024-01-01",
-  // due_date: undefined
+await repo.updatePost({
+  id: 'post_1',
+  title: 'Updated title',
+  // body: undefined → not updated
 });
 ```
 
 ```sql
 -- expands to
-UPDATE invoices
-SET updated_at = now(), invoice_date = ?
+UPDATE posts
+SET updated_at = now(), title = ?
 WHERE id = ?;
 ```