sonamu 0.9.19 → 0.9.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sonamu",
-  "version": "0.9.19",
+  "version": "0.9.20",
   "description": "Sonamu — TypeScript Fullstack API Framework",
   "keywords": [
     "framework",
@@ -130,8 +130,8 @@
     "vite": "8.0.5",
     "vitest": "^4.1.2",
     "@sonamu-kit/hmr-runner": "^0.2.0",
+    "@sonamu-kit/tasks": "^0.3.1",
     "@sonamu-kit/ts-loader": "^2.2.0",
-    "@sonamu-kit/tasks": "^0.3.0",
     "@sonamu-kit/hmr-hook": "^0.5.1"
   },
   "devDependencies": {

package/src/skills/sonamu/entity-basic.md

@@ -436,6 +436,37 @@ SQL expressions per source column type:
 }
 ```
 
+### Partial index (`where`)
+
+`where` declares a PostgreSQL partial index predicate. Provide a raw SQL condition **without** the `WHERE` keyword; it is appended to the generated `CREATE INDEX`. Works for every index type (`index`, `unique`, `hnsw`, `ivfflat`, pgroonga).
+
+```json
+{
+  "name": "uniq_users_email_active",
+  "type": "unique",
+  "columns": [{ "name": "email" }],
+  "where": "deleted_at IS NULL"
+}
+```
+
+→ `CREATE UNIQUE INDEX uniq_users_email_active ON users (email) WHERE deleted_at IS NULL;`
+(Enforces email uniqueness only among non-deleted rows.)
+
+### `nullsNotDistinct` (unique only)
+
+By default PostgreSQL treats `NULL`s as distinct, so a unique index allows multiple `NULL` rows. Set `nullsNotDistinct: true` to emit `NULLS NOT DISTINCT`, treating `NULL`s as equal (at most one `NULL` allowed).
+
+```json
+{
+  "name": "uniq_accounts_external_id",
+  "type": "unique",
+  "columns": [{ "name": "external_id" }],
+  "nullsNotDistinct": true
+}
+```
+
+→ `CREATE UNIQUE INDEX uniq_accounts_external_id ON accounts (external_id) NULLS NOT DISTINCT;`
+
 ### IMPORTANT: Use the actual DB column name in indexes
 
 **The way FK columns are referenced differs between indexes and subsets. Do not confuse them.**

package/src/skills/sonamu/puri.md

@@ -180,6 +180,28 @@ db.table("orders")
 db.orderBy("created_at", "desc").limit(20).offset(40); // Page 3
 ```
 
+### NULLS position & array form
+
+`orderBy` has two overloads:
+
+1. Single column: `orderBy(column, direction?, nulls?)` — `nulls` is `"first" | "last"`
+2. Array: `orderBy(entries[])` — each entry is a column string, a `Puri.raw*` SQL expression, or an object `{ column, order?, nulls? }`
+
+```typescript
+// Single column with NULLS position
+db.orderBy("published_at", "desc", "last");
+
+// Array form: multiple sort keys, per-key direction and NULLS
+db.orderBy([
+  { column: "is_pinned", order: "desc" },
+  { column: "published_at", order: "desc", nulls: "last" },
+  "title", // bare string defaults to asc
+]);
+
+// Sort by a SQL expression
+db.orderBy([Puri.rawNumber("view_count * 2"), { column: "id", order: "desc" }]);
+```
+
 ## GROUP BY & HAVING
 
 ```typescript

package/src/skills/sonamu/upsert.md

@@ -1,6 +1,6 @@
 ---
 name: sonamu-upsert
-description: Saving complex relational data with Sonamu UpsertBuilder. ubRegister, ubUpsert, insertOnly, updateBatch patterns, FK ordering, cleanOrphans. Use when saving related data with foreign key dependencies.
+description: Saving complex relational data with Sonamu UpsertBuilder. ubRegister, ubUpsert, ubInsertOnly, ubUpdateBatch, bulk insert/upsert patterns, FK ordering, cleanOrphans. Use when saving related data with foreign key dependencies.
 ---
 
 # UpsertBuilder
@@ -178,15 +178,62 @@ await wdb.transaction(async (trx) => {
 });
 ```
 
-## insertOnly (INSERT Only)
+## Bulk Insert / Bulk Upsert (Large Datasets)
+
+**Principle (same as regular saves):** call `ubRegister` for every row **outside** the transaction, then call only `ubUpsert` / `ubInsertOnly` **inside** the transaction. Split large datasets with `chunkSize`. Calling `ubRegister` inside the transaction is reserved for the special case where a row depends on the real id produced by a preceding `ubUpsert`.
+
+### (a) Bulk insert inside a Model
+
+```typescript
+async createMany(params: PostCreateParams[]): Promise<number[]> {
+  const wdb = this.getPuri("w");
+  params.forEach((p) => wdb.ubRegister("posts", p));
+
+  return wdb.transaction(async (trx) => {
+    return trx.ubInsertOnly("posts", { chunkSize: 5000 });
+  });
+}
+```
+
+### (b) Standalone Puri (seed / batch scripts outside a Model)
+
+Outside a Model there is no `this.getPuri("w")`, so build a `PuriWrapper` directly. Use `DB.getDB("w")` only in this script context — inside Models always use `getPuri("w")`.
+
+```typescript
+import { DB, PuriWrapper, UpsertBuilder } from "sonamu";
+
+const puri = new PuriWrapper(DB.getDB("w"), new UpsertBuilder());
+for (const row of rows) puri.ubRegister("audit_logs", row);
+
+await puri.transaction(async (trx) => {
+  await trx.ubInsertOnly("audit_logs", { chunkSize: 5000 }); // or ubUpsert
+});
+```
+
+### (c) Multiple tables in one transaction (FK order)
+
+Register every table outside the transaction, then upsert parents before children.
+
+```typescript
+const puri = new PuriWrapper(DB.getDB("w"), new UpsertBuilder());
+for (const row of postRows) puri.ubRegister("posts", row);
+for (const row of tagRows) puri.ubRegister("post_tags", row);
+
+await puri.transaction(async (trx) => {
+  await trx.ubInsertOnly("posts", { chunkSize: 5000 }); // parent first
+  await trx.ubInsertOnly("post_tags", { chunkSize: 5000 }); // child next
+});
+```
+
+## ubInsertOnly (INSERT Only)
 
 Perform INSERT without UPDATE:
 
 ```typescript
-await trx.insertOnly("logs", { chunkSize: 1000 });
+await trx.ubInsertOnly("logs", { chunkSize: 1000 });
 ```
 
-## updateBatch (Batch Update)
+## ubUpdateBatch (Batch Update)
 
 Bulk UPDATE operations:
 
@@ -197,14 +244,14 @@ wdb.ubRegister("users", { id: 2, status: "active" });
 wdb.ubRegister("users", { id: 3, status: "inactive" });
 
 await wdb.transaction(async (trx) => {
-  await trx.updateBatch("users", {
+  await trx.ubUpdateBatch("users", {
     chunkSize: 500, // batch size (default: 500)
     where: "id", // WHERE condition column (default: "id")
   });
 });
 
 // Composite key for WHERE condition
-await trx.updateBatch("user_settings", {
+await trx.ubUpdateBatch("user_settings", {
   where: ["user_id", "setting_key"],
 });
 ```