sonamu 0.8.26 → 0.9.0

package/src/skills/sonamu/testing-devrunner.md

@@ -45,6 +45,7 @@ export default defineConfig({
 ```
 
 Configuration type (`SonamuDevRunnerConfig`):
+
 - `enabled: boolean` — Whether to enable DevRunner (default: false)
 - `routePrefix?: string` — Test endpoint path prefix (default: `/__test__`)
 - `vitestConfigPath?: string` — vitest.config.ts path (relative to api-root)
@@ -82,6 +83,7 @@ sonamu test user.model -p "findMany" -t
 ```
 
 Argument processing rules:
+
 - `--pattern` / `-p`: test name string filter (`setGlobalTestNamePattern` → `resetGlobalTestNamePattern` after execution)
 - `--traces` / `-t`: boolean flag, enables Naite trace output
 - Arguments not starting with `-`: treated as file list
@@ -115,6 +117,7 @@ For trace data details: see `naite.md`
 ### HMR Integration — Automatic Vitest Module Graph Invalidation on Source Changes
 
 When a source file is modified, `syncFromWatcher` in the syncer triggers both of the following simultaneously:
+
 1. Server HMR cache invalidation (`hot.invalidateFile`)
 2. Vitest module graph invalidation (`Sonamu.devVitestManager.invalidateFiles([filePath])`)
 
@@ -127,6 +130,7 @@ sonamu test user.model  ← runs with latest code
 Because Vite's `moduleGraph.invalidateModule()` recursively cascades in the importer direction, invalidating a single source file automatically invalidates any test files that import it. No restart is needed.
 
 **Transitive dependency example:**
+
 - Change `utils.ts` → `user.model.ts` (imports utils) → `user.model.test.ts` all automatically invalidated
 
 ### Direct HTTP API Calls
@@ -144,24 +148,36 @@ curl http://localhost:3000/__test__/status
 ```
 
 **POST `/__test__/run`** request:
+
 ```json
 { "files": ["src/user/user.model.test.ts"], "pattern": "should create user" }
 ```
 
 Response (success):
+
 ```json
 {
   "ok": true,
   "summary": { "total": 12, "passed": 11, "failed": 1, "skipped": 0, "durationMs": 842 },
   "failed": [
-    { "file": "src/user/user.model.test.ts", "name": "UserModel > should create user", "error": "Expected ..." }
+    {
+      "file": "src/user/user.model.test.ts",
+      "name": "UserModel > should create user",
+      "error": "Expected ..."
+    }
   ],
   "traces": [
     {
       "testName": "UserModel > should create user",
       "file": "src/user/user.model.test.ts",
       "traces": [
-        { "key": "esq-query", "value": "select ...", "filePath": "user.model.ts", "lineNumber": 113, "at": "2026-02-23T14:51:35+09:00" }
+        {
+          "key": "esq-query",
+          "value": "select ...",
+          "filePath": "user.model.ts",
+          "lineNumber": 113,
+          "at": "2026-02-23T14:51:35+09:00"
+        }
       ]
     }
   ]
@@ -169,6 +185,7 @@ Response (success):
 ```
 
 **GET `/__test__/status`** response:
+
 ```json
 { "ready": true, "running": false, "lastRunAt": "2026-02-13T12:34:56.000Z" }
 ```
@@ -176,6 +193,7 @@ Response (success):
 ### Internal Architecture
 
 **DevVitestManager** (`testing/dev-vitest-manager.ts`):
+
 - Creates a resident instance with `createVitest('test', cliOptions, viteOverrides)`
 - Configured with `watch: true, standalone: true`, but blocks automatic re-runs:
   - `forceRerunTriggers: []`
@@ -187,11 +205,13 @@ Response (success):
 - Keeps loading the project's `vitest.config.ts` (reuses existing sequencer/reporter/globalSetup)
 
 **Fastify integration** (`testing/dev-test-routes.ts`):
+
 - Registers routes with `registerDevTestRoutes(server, config)`
 - Stores manager instance in `Sonamu.devVitestManager`
 - Ensures `shutdown()` is called in `server.addHook('onClose')`
 
 **CLI** (`bin/test-command.ts`):
+
 - Calls `testCommand()` directly before `tsicli` matching (to handle variadic arguments)
 - Included in `bootstrap()`'s `notToInit` list (no need for `Sonamu.init` since it only makes HTTP calls)
 - Server port/host read from `server.listen` in `sonamu.config.ts`
@@ -200,30 +220,30 @@ Response (success):
 
 Single file (`user.model.test.ts`):
 
-| Item | `vitest run` | `sonamu test` | Difference |
-|---|---|---|---|
-| Test execution time | 2,610ms | 823ms | 3.2x faster |
-| Total elapsed time (wall clock) | 4,118ms | 1,907ms | 2.2x faster |
+| Item                            | `vitest run` | `sonamu test` | Difference  |
+| ------------------------------- | ------------ | ------------- | ----------- |
+| Test execution time             | 2,610ms      | 823ms         | 3.2x faster |
+| Total elapsed time (wall clock) | 4,118ms      | 1,907ms       | 2.2x faster |
 
 Multiple files (puri tests, 4 files 147 tests):
 
-| Item | `vitest run` | `sonamu test` | Difference |
-|---|---|---|---|
-| Test execution time | 5,740ms | 1,774ms | 3.2x faster |
-| Total elapsed time (wall clock) | 7,035ms | 2,673ms | 2.6x faster |
+| Item                            | `vitest run` | `sonamu test` | Difference  |
+| ------------------------------- | ------------ | ------------- | ----------- |
+| Test execution time             | 5,740ms      | 1,774ms       | 3.2x faster |
+| Total elapsed time (wall clock) | 7,035ms      | 2,673ms       | 2.6x faster |
 
 Speed difference reason: `vitest run` requires process boot (~1.5s) + module transform (~400ms) on every execution, whereas `sonamu test` reuses an already-initialized instance and avoids this overhead.
 
 ### `pnpm sonamu test` vs `pnpm test` Comparison
 
-| | `pnpm sonamu test` (default) | `pnpm test` (CI/fallback) |
-|---|---|---|
-| Execution method | Resident instance inside dev server | Independent Vitest process |
-| Initialization cost | None (already initialized) | Initialization on every run |
-| HMR integration | Source changes reflected immediately | Not applicable |
-| Naite trace | CLI output via `--traces` flag | Available through reporter |
-| Use case | **Default test execution during development** | CI environments |
-| Prerequisite | `sonamu dev` running (assumed always running) | None |
+|                     | `pnpm sonamu test` (default)                  | `pnpm test` (CI/fallback)   |
+| ------------------- | --------------------------------------------- | --------------------------- |
+| Execution method    | Resident instance inside dev server           | Independent Vitest process  |
+| Initialization cost | None (already initialized)                    | Initialization on every run |
+| HMR integration     | Source changes reflected immediately          | Not applicable              |
+| Naite trace         | CLI output via `--traces` flag                | Available through reporter  |
+| Use case            | **Default test execution during development** | CI environments             |
+| Prerequisite        | `sonamu dev` running (assumed always running) | None                        |
 
 ### Troubleshooting
 
@@ -275,8 +295,8 @@ Both `pnpm sonamu test` and `pnpm test` share the parallel configuration. Only c
 ```typescript
 export default defineConfig({
   test: {
-    parallel: true,   // Separate DB execution per worker
-    maxWorkers: 4,    // Number of workers (default: 4)
+    parallel: true, // Separate DB execution per worker
+    maxWorkers: 4, // Number of workers (default: 4)
   },
 });
 ```
@@ -291,14 +311,14 @@ To use `pnpm sonamu test`, DevRunner must be enabled. Just add `test.devRunner.e
 export default defineConfig({
   server: {
     listen: {
-      port: 3000,          // CLI sends HTTP requests to this port
-      host: "localhost",   // CLI connects to this host (default: localhost)
+      port: 3000, // CLI sends HTTP requests to this port
+      host: "localhost", // CLI connects to this host (default: localhost)
     },
   },
 
   test: {
     devRunner: {
-      enabled: true,                     // Required: enable DevRunner
+      enabled: true, // Required: enable DevRunner
       // routePrefix: "/__test__",       // Optional: endpoint path (default value)
       // vitestConfigPath: undefined,     // Optional: vitest.config.ts path (default: vitest.config.ts in api-root)
     },
@@ -310,16 +330,16 @@ export default defineConfig({
 
 ### Source Code Reference Locations per Setting
 
-| Setting path | Default | Reference location | Purpose |
-|---|---|---|---|
-| `test.devRunner.enabled` | `false` | `sonamu.ts` L394, `test-command.ts` | DevRunner activation condition |
-| `test.devRunner.routePrefix` | `"/__test__"` | `dev-test-routes.ts`, `test-command.ts` | HTTP endpoint path |
-| `test.devRunner.vitestConfigPath` | `undefined` | `dev-vitest-manager.ts` `start()` | Vitest config file location |
-| `test.parallel` | `false` | `vitest-helpers.ts` `getSonamuTestConfig()` | `pool: "forks"` + `SONAMU_WORKER_DB` env injection |
-| `test.maxWorkers` | `4` | `vitest-helpers.ts`, `global-setup.ts` | Vitest maxWorkers + number of worker DBs |
-| `server.listen.port` | `3000` | `test-command.ts` | CLI → dev server HTTP connection port |
-| `server.listen.host` | `"localhost"` | `test-command.ts` | CLI → dev server HTTP connection host |
-| `database.name` | — | `db.ts` `generateDBConfig()`, `global-setup.ts` | Test DB name (`{name}_test`) |
+| Setting path                      | Default       | Reference location                              | Purpose                                            |
+| --------------------------------- | ------------- | ----------------------------------------------- | -------------------------------------------------- |
+| `test.devRunner.enabled`          | `false`       | `sonamu.ts` L394, `test-command.ts`             | DevRunner activation condition                     |
+| `test.devRunner.routePrefix`      | `"/__test__"` | `dev-test-routes.ts`, `test-command.ts`         | HTTP endpoint path                                 |
+| `test.devRunner.vitestConfigPath` | `undefined`   | `dev-vitest-manager.ts` `start()`               | Vitest config file location                        |
+| `test.parallel`                   | `false`       | `vitest-helpers.ts` `getSonamuTestConfig()`     | `pool: "forks"` + `SONAMU_WORKER_DB` env injection |
+| `test.maxWorkers`                 | `4`           | `vitest-helpers.ts`, `global-setup.ts`          | Vitest maxWorkers + number of worker DBs           |
+| `server.listen.port`              | `3000`        | `test-command.ts`                               | CLI → dev server HTTP connection port              |
+| `server.listen.host`              | `"localhost"` | `test-command.ts`                               | CLI → dev server HTTP connection host              |
+| `database.name`                   | —             | `db.ts` `generateDBConfig()`, `global-setup.ts` | Test DB name (`{name}_test`)                       |
 
 ### Activation Conditions
 
@@ -372,10 +392,10 @@ export { setup } from "sonamu/test";
 ```typescript
 export default defineConfig({
   test: {
-    parallel: true,   // Enable parallel testing
-    maxWorkers: 4,    // Number of workers (default: 4)
+    parallel: true, // Enable parallel testing
+    maxWorkers: 4, // Number of workers (default: 4)
     devRunner: {
-      enabled: true,  // Enable DevRunner
+      enabled: true, // Enable DevRunner
     },
   },
 });

package/src/skills/sonamu/testing.md

@@ -35,9 +35,7 @@ import PostModel from "../post/post.model";
 import CommentModel from "../comment/comment.model";
 
 // User helper
-export async function createTestUser(
-  params?: Partial<UserSaveParams>,
-): Promise<number> {
+export async function createTestUser(params?: Partial<UserSaveParams>): Promise<number> {
   const user: UserSaveParams = {
     email: `test-${Date.now()}@example.com`,
     name: "Test User",
@@ -598,11 +596,7 @@ export async function createTestConsultationWithDeps() {
     role: "counselor",
   });
   const damageTypeId = await createTestDamageType(null);
-  const consultationId = await createTestConsultation(
-    applicantId,
-    counselorId,
-    damageTypeId,
-  );
+  const consultationId = await createTestConsultation(applicantId, counselorId, damageTypeId);
   return { applicantId, counselorId, damageTypeId, consultationId };
 }
 ```
@@ -625,8 +619,7 @@ This is what differentiates it from simple CRUD tests, and it's **the core that
 describe("E. Business Logic", () => {
   test("full process from consultation submission to completion", async () => {
     // 1. submit consultation + create dependencies
-    const { consultationId, counselorId } =
-      await createTestConsultationWithDeps();
+    const { consultationId, counselorId } = await createTestConsultationWithDeps();
     // 2. record channel logs (online submission, phone consultation)
     await createTestConsultationChannelLog(consultationId, {
       channel: "online",
@@ -785,12 +778,12 @@ const [id] = await FAQModel.save([
 
 #### Application Criteria
 
-| Field type | Handling |
+| Field type                       | Handling                        |
 | -------------------------------- | ------------------------------- |
 | `id`, `created_at`, `updated_at` | Always partial (auto-generated) |
-| Fields with `dbDefault` | `.optional().default(value)` |
-| Fields with `nullable: true` | partial + extend + `.nullish()` |
-| Required fields | Excluded from partial |
+| Fields with `dbDefault`          | `.optional().default(value)`    |
+| Fields with `nullable: true`     | partial + extend + `.nullish()` |
+| Required fields                  | Excluded from partial           |
 
 #### Checklist
 
@@ -872,12 +865,12 @@ expect(item?.field).toBe(expectedValue); // find() can return undefined
 
 Sonamu Model provides the following methods by default. Tests are written targeting these methods:
 
-| Method | Purpose | Returns |
-| -------------------------- | ------------------ | ----------------------------- |
-| `findById(subset, id)` | Fetch single record | `Promise<Subset>` |
-| `findMany(subset, params)` | Fetch list | `Promise<ListResult<Subset>>` |
-| `save(rows)` | Create/update (upsert) | `Promise<number[]>` (ids) |
-| `del(ids)` | Delete | `Promise<number>` (delete count) |
+| Method                     | Purpose                | Returns                          |
+| -------------------------- | ---------------------- | -------------------------------- |
+| `findById(subset, id)`     | Fetch single record    | `Promise<Subset>`                |
+| `findMany(subset, params)` | Fetch list             | `Promise<ListResult<Subset>>`    |
+| `save(rows)`               | Create/update (upsert) | `Promise<number[]>` (ids)        |
+| `del(ids)`                 | Delete                 | `Promise<number>` (delete count) |
 
 **Note:** It's `del`, not `delete`. This avoids JavaScript reserved words.
 
@@ -1231,9 +1224,7 @@ test("validate select query", async () => {
 
   expectQuery(query, "type").toBe("select");
   expectQuery(query, "table").toBe("users");
-  expectQuery(query, "columns").toMatchInlineSnapshot(
-    `""users"."id" AS \`id\`"`,
-  );
+  expectQuery(query, "columns").toMatchInlineSnapshot(`""users"."id" AS \`id\`"`);
 });
 
 test("validate where condition", async () => {
@@ -1246,9 +1237,7 @@ test("validate where condition", async () => {
 
 test("validate join", async () => {
   const db = UserModel.getPuri("r");
-  await db
-    .table("employees")
-    .leftJoin("departments", "employees.department_id", "departments.id");
+  await db.table("employees").leftJoin("departments", "employees.department_id", "departments.id");
   const query = Naite.get("puri:executed-query").first();
 
   expectQuery(query, "join").toMatchInlineSnapshot(
@@ -1427,9 +1416,7 @@ test("unresolved reference error", async () => {
   ub.register("departments", { company_id: companyRef, name: "Dept" });
 
   // attempt upsert in wrong order
-  await expect(ub.upsert(wdb, "departments")).rejects.toThrow(
-    /unresolved reference/,
-  );
+  await expect(ub.upsert(wdb, "departments")).rejects.toThrow(/unresolved reference/);
 });
 ```
 
@@ -1572,10 +1559,7 @@ SaveParams types are exported from each entity's types.ts, not from sonamu.gener
 
 ```typescript
 // test-helpers.ts
-import type {
-  UserSaveParams,
-  TaskSaveParams,
-} from "../application/sonamu.generated"; // WRONG
+import type { UserSaveParams, TaskSaveParams } from "../application/sonamu.generated"; // WRONG
 ```
 
 **Correct:**
@@ -1870,9 +1854,7 @@ function uniqueId(prefix: string) {
   return `${prefix}_${Date.now()}_${++counter}`;
 }
 
-export async function createTestInstitution(
-  override?: Partial<InstitutionSaveParams>,
-) {
+export async function createTestInstitution(override?: Partial<InstitutionSaveParams>) {
   const [id] = await InstitutionModel.save([
     {
       name: "Test Institution",
@@ -1903,10 +1885,7 @@ export async function createTestDepartment(
   return id;
 }
 
-export async function createTestUser(
-  institutionId: number,
-  override?: Partial<UserSaveParams>,
-) {
+export async function createTestUser(institutionId: number, override?: Partial<UserSaveParams>) {
   const [id] = await UserModel.save([
     {
       employee_no: uniqueId("EMP"),
@@ -1940,18 +1919,14 @@ export async function createTestTask(
 }
 
 // create the entire dependency chain at once
-export async function createTestTaskWithDeps(
-  taskOverride?: Partial<TaskSaveParams>,
-) {
+export async function createTestTaskWithDeps(taskOverride?: Partial<TaskSaveParams>) {
   const institutionId = await createTestInstitution();
   const userId = await createTestUser(institutionId);
   const taskId = await createTestTask(userId, taskOverride);
   return { institutionId, userId, taskId };
 }
 
-export async function createTestUserWithDeps(
-  userOverride?: Partial<UserSaveParams>,
-) {
+export async function createTestUserWithDeps(userOverride?: Partial<UserSaveParams>) {
   const institutionId = await createTestInstitution();
   const userId = await createTestUser(institutionId, userOverride);
   return { institutionId, userId };
@@ -2005,14 +1980,7 @@ When modifying findById results and saving again, relations must be converted to
 
 // Task Subset A → SaveParams conversion
 export function taskToSaveParams(task: TaskSubsetA): TaskSaveParams {
-  const {
-    program,
-    project,
-    principal_investigator,
-    department,
-    prev_task,
-    ...rest
-  } = task;
+  const { program, project, principal_investigator, department, prev_task, ...rest } = task;
 
   return {
     ...rest,
@@ -2047,10 +2015,7 @@ export function relationToFk<T extends Record<string, any>>(
 ### Simplifying Update Tests
 
 ```typescript
-import {
-  createTestTaskWithDeps,
-  taskToSaveParams,
-} from "../../testing/test-helpers";
+import { createTestTaskWithDeps, taskToSaveParams } from "../../testing/test-helpers";
 
 test("Update - update task info", async () => {
   const { taskId } = await createTestTaskWithDeps();

package/src/skills/sonamu/upsert.md

@@ -11,9 +11,9 @@ The reference object returned by `ubRegister()`:
 
 ```typescript
 type UBRef = {
-  uuid: string;   // unique identifier
-  of: string;     // table name
-  use?: string;   // field to reference (default: "id")
+  uuid: string; // unique identifier
+  of: string; // table name
+  use?: string; // field to reference (default: "id")
 };
 ```
 
@@ -30,8 +30,8 @@ wdb.ubRegister("employees", { user_id: userRef, department_id: deptId });
 
 // Save in order inside a transaction
 return wdb.transaction(async (trx) => {
-  await trx.ubUpsert("users");       // Save first (referenced by FK)
-  return trx.ubUpsert("employees");  // Save after (uses FK)
+  await trx.ubUpsert("users"); // Save first (referenced by FK)
+  return trx.ubUpsert("employees"); // Save after (uses FK)
 });
 ```
 
@@ -54,12 +54,13 @@ wdb.ubRegister("posts", {
 wdb.ubRegister("posts", {
   id: 1,
   title: "Updated Title",
-  content: "Updated Content",  // required field included!
-  author_id: 1,                // FK also included if required!
+  content: "Updated Content", // required field included!
+  author_id: 1, // FK also included if required!
 });
 ```
 
 **How to identify required fields**:
+
 1. Check props in entity.json
 2. Fields without `nullable: true` = required fields
 3. `id`, `created_at`, fields with `dbDefault` can be omitted
@@ -68,11 +69,11 @@ wdb.ubRegister("posts", {
 // entity.json example
 {
   "props": [
-    { "name": "id", "type": "integer" },  // can be omitted
-    { "name": "title", "type": "string" },  // required! (no nullable)
-    { "name": "content", "type": "string" },  // required! (no nullable)
-    { "name": "category", "type": "string", "nullable": true },  // optional
-    { "name": "created_at", "type": "date", "dbDefault": "CURRENT_TIMESTAMP" }  // can be omitted
+    { "name": "id", "type": "integer" }, // can be omitted
+    { "name": "title", "type": "string" }, // required! (no nullable)
+    { "name": "content", "type": "string" }, // required! (no nullable)
+    { "name": "category", "type": "string", "nullable": true }, // optional
+    { "name": "created_at", "type": "date", "dbDefault": "CURRENT_TIMESTAMP" } // can be omitted
   ]
 }
 ```
@@ -82,10 +83,10 @@ wdb.ubRegister("posts", {
 Save the table referenced by FK first:
 
 ```typescript
-await trx.ubUpsert("companies");   // 1. No dependencies
+await trx.ubUpsert("companies"); // 1. No dependencies
 await trx.ubUpsert("departments"); // 2. Needs company_id
-await trx.ubUpsert("users");       // 3. No dependencies
-await trx.ubUpsert("employees");   // 4. Needs user_id, department_id
+await trx.ubUpsert("users"); // 3. No dependencies
+await trx.ubUpsert("employees"); // 4. Needs user_id, department_id
 ```
 
 ## Model save Pattern
@@ -165,10 +166,10 @@ In hierarchical structures (e.g. categories, org charts), self-referential relat
 await wdb.transaction(async (trx) => {
   // Root category
   const rootRef = trx.ubRegister("categories", { name: "Root", parent_id: null });
-  
+
   // Child category (references rootRef)
   const childRef = trx.ubRegister("categories", { name: "Child", parent_id: rootRef });
-  
+
   // Grandchild category (references childRef)
   trx.ubRegister("categories", { name: "Grandchild", parent_id: childRef });
 
@@ -197,8 +198,8 @@ wdb.ubRegister("users", { id: 3, status: "inactive" });
 
 await wdb.transaction(async (trx) => {
   await trx.updateBatch("users", {
-    chunkSize: 500,      // batch size (default: 500)
-    where: "id",         // WHERE condition column (default: "id")
+    chunkSize: 500, // batch size (default: 500)
+    where: "id", // WHERE condition column (default: "id")
   });
 });
 
@@ -214,9 +215,9 @@ Options for `ubUpsert()`:
 
 ```typescript
 type UpsertOptions = {
-  chunkSize?: number;      // batch size
-  cleanOrphans?: string | string[];  // FK column(s) to use as basis for deleting orphan records
-  inherit?: string[];      // columns to preserve existing values on UPDATE
+  chunkSize?: number; // batch size
+  cleanOrphans?: string | string[]; // FK column(s) to use as basis for deleting orphan records
+  inherit?: string[]; // columns to preserve existing values on UPDATE
 };
 ```
 
@@ -235,7 +236,7 @@ Automatically delete orphan records based on FK:
 ```typescript
 // Single FK
 await trx.ubUpsert("order_items", {
-  cleanOrphans: "order_id",  // delete records with the same order_id that were not upserted this time
+  cleanOrphans: "order_id", // delete records with the same order_id that were not upserted this time
 });
 
 // Composite FK
@@ -250,7 +251,7 @@ Preserve existing values for specific columns on UPDATE:
 
 ```typescript
 await trx.ubUpsert("users", {
-  inherit: ["created_at", "password"],  // these columns are excluded from UPDATE
+  inherit: ["created_at", "password"], // these columns are excluded from UPDATE
 });
 ```
 
@@ -259,16 +260,16 @@ await trx.ubUpsert("users", {
 Select upsert or insert mode at runtime.
 
 ```typescript
-await trx.ubUpsertOrInsert("logs", "insert");   // INSERT only
-await trx.ubUpsertOrInsert("users", "upsert");  // UPSERT (default)
+await trx.ubUpsertOrInsert("logs", "insert"); // INSERT only
+await trx.ubUpsertOrInsert("users", "upsert"); // UPSERT (default)
 await trx.ubUpsertOrInsert("users", "upsert", { cleanOrphans: "team_id" });
 ```
 
-| Parameter | Type | Description |
-|----------|------|------|
-| `tableName` | string | table name |
-| `mode` | `"upsert"` \| `"insert"` | operation mode |
-| `options` | `UpsertOptions` | chunkSize, cleanOrphans, inherit (same as ubUpsert) |
+| Parameter   | Type                     | Description                                         |
+| ----------- | ------------------------ | --------------------------------------------------- |
+| `tableName` | string                   | table name                                          |
+| `mode`      | `"upsert"` \| `"insert"` | operation mode                                      |
+| `options`   | `UpsertOptions`          | chunkSize, cleanOrphans, inherit (same as ubUpsert) |
 
 When `mode: "insert"`, unlike `insertOnly`, `UpsertOptions` (cleanOrphans, inherit) can be used.