sonamu 0.10.7 → 0.10.9

package/src/skills/sonamu-query/references/upsert.md

@@ -1,324 +0,0 @@
-# UpsertBuilder — Batch Saving Relation Data
-
-## UBRef Type
-
-The reference object returned by `ubRegister()`:
-
-```typescript
-type UBRef = {
-  uuid: string; // unique identifier
-  of: string; // table name
-  use?: string; // field to reference (default: "id")
-};
-```
-
-## Basic Pattern
-
-```typescript
-const wdb = this.getPuri("w");
-
-// Register data (returns UBRef)
-const userRef = wdb.ubRegister("users", { email: "john@test.com", username: "john" });
-
-// Use UBRef in related data
-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)
-});
-```
-
-## CRITICAL: All Required Fields Must Be Included
-
-**ubUpsert uses PostgreSQL's `ON CONFLICT ... DO UPDATE` query.**
-
-Even when updating, **all required fields (fields with NOT NULL constraints)** must be included.
-
-```typescript
-// BAD - missing required field
-wdb.ubRegister("posts", {
-  id: 1,
-  title: "Updated Title",
-  // content required field missing! → ON CONFLICT UPDATE tries to set NULL → DB error
-});
-// Error: null value in column "content" violates not-null constraint
-
-// GOOD - all required fields included
-wdb.ubRegister("posts", {
-  id: 1,
-  title: "Updated Title",
-  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
-
-```json
-// 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
-  ]
-}
-```
-
-## Save Order (Important!)
-
-Save the table referenced by FK first:
-
-```typescript
-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
-```
-
-## Model save Pattern
-
-```typescript
-@api({ httpMethod: "POST" })
-async save(spa: UserSaveParams[]): Promise<number[]> {
-  const wdb = this.getPuri("w");
-  spa.forEach((sp) => wdb.ubRegister("users", sp));
-
-  return wdb.transaction(async (trx) => {
-    return trx.ubUpsert("users");
-  });
-}
-```
-
-## Saving Related Data
-
-```typescript
-await this.getPuri("w").transaction(async (trx) => {
-  // Register User
-  const userRef = trx.ubRegister("users", {
-    email: data.email,
-    username: data.username,
-    password: bcrypt.hashSync(data.password, 10),
-  });
-
-  // Register Employee (using userRef)
-  trx.ubRegister("employees", {
-    user_id: userRef,
-    department_id: data.departmentId,
-    salary: data.salary,
-  });
-
-  // Save in order
-  await trx.ubUpsert("users");
-  const [employeeId] = await trx.ubUpsert("employees");
-  return employeeId;
-});
-```
-
-## Upsert (Insert or Update)
-
-```typescript
-// INSERT when no id
-wdb.ubRegister("users", { email: "new@test.com", username: "new" });
-
-// UPDATE when id is present
-wdb.ubRegister("users", { id: 1, email: "updated@test.com" });
-```
-
-**Conflict handling**: If the Entity has a unique index, automatically pre-fetches to populate the existing record's id, then performs UPDATE
-
-## ManyToMany Relationships
-
-```typescript
-await wdb.transaction(async (trx) => {
-  const projectRef = trx.ubRegister("projects", { name: "Project A" });
-
-  for (const empId of employeeIds) {
-    trx.ubRegister("projects__employees", {
-      project_id: projectRef,
-      employee_id: empId,
-    });
-  }
-
-  await trx.ubUpsert("projects");
-  await trx.ubUpsert("projects__employees");
-});
-```
-
-## Self-Reference
-
-In hierarchical structures (e.g. categories, org charts), self-referential relationships are automatically processed level by level:
-
-```typescript
-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 });
-
-  // Internally processed level by level (Root → Child → Grandchild)
-  await trx.ubUpsert("categories");
-});
-```
-
-## 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.ubInsertOnly("logs", { chunkSize: 1000 });
-```
-
-## ubUpdateBatch (Batch Update)
-
-Bulk UPDATE operations:
-
-```typescript
-// Register multiple records
-wdb.ubRegister("users", { id: 1, status: "active" });
-wdb.ubRegister("users", { id: 2, status: "active" });
-wdb.ubRegister("users", { id: 3, status: "inactive" });
-
-await wdb.transaction(async (trx) => {
-  await trx.ubUpdateBatch("users", {
-    chunkSize: 500, // batch size (default: 500)
-    where: "id", // WHERE condition column (default: "id")
-  });
-});
-
-// Composite key for WHERE condition
-await trx.ubUpdateBatch("user_settings", {
-  where: ["user_id", "setting_key"],
-});
-```
-
-## UpsertOptions
-
-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
-
-Specify batch size for large data processing:
-
-```typescript
-await trx.ubUpsert("logs", { chunkSize: 1000 });
-```
-
-### cleanOrphans
-
-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
-});
-
-// Composite FK
-await trx.ubUpsert("project_members", {
-  cleanOrphans: ["project_id", "team_id"],
-});
-```
-
-### inherit
-
-Preserve existing values for specific columns on UPDATE:
-
-```typescript
-await trx.ubUpsert("users", {
-  inherit: ["created_at", "password"], // these columns are excluded from UPDATE
-});
-```
-
-## ubUpsertOrInsert (Conditional Mode)
-
-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("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) |
-
-When `mode: "insert"`, unlike `insertOnly`, `UpsertOptions` (cleanOrphans, inherit) can be used.
-
-## Rules
-
-- MUST use inside `transaction()`
-- MUST call `ubUpsert()` for FK-referenced tables first (correct order)
-- UBRef can ONLY be used inside `ubRegister` (not for direct DB queries)
-- Self-reference is auto-handled by level-based insertion
-- Unique index conflicts are auto-resolved by pre-fetching existing IDs

package/src/skills/sonamu-tasks/SKILL.md

@@ -1,236 +0,0 @@
----
-name: sonamu-tasks
-description: Runs background work with Sonamu Tasks. Use when implementing a background job, scheduling recurring work, or building a multi-step process that must survive a restart. Covers durable steps, cron scheduling, retry policies, and the task worker.
----
-
-# Tasks (Workflow System)
-
-PostgreSQL-based durable workflow engine. Uses the `@sonamu-kit/tasks` package.
-
-**Source code:**
-
-- Decorator: `modules/sonamu/src/tasks/decorator.ts`
-- StepWrapper: `modules/sonamu/src/tasks/step-wrapper.ts`
-- WorkflowManager: `modules/sonamu/src/tasks/workflow-manager.ts`
-- @sonamu-kit/tasks: `modules/tasks/`
-
-## Workflow Definition
-
-Define with the `workflow()` function. When exported, the syncer automatically collects and registers it with WorkflowManager.
-
-```typescript
-import { workflow } from "sonamu";
-
-// Method 1: decorator + function separated
-export const myTask = workflow({
-  version: "1",
-})(async ({ input, step, logger, version }) => {
-  // ...
-});
-
-// Method 2: decorator + function inlined
-export const myTask = workflow(
-  {
-    version: "1",
-  },
-  async ({ input, step, logger, version }) => {
-    // ...
-  },
-);
-```
-
-### DefineWorkflowOptions
-
-| Option        | Type               | Required | Description                                                         |
-| ------------- | ------------------ | -------- | ------------------------------------------------------------------- |
-| `version`     | `string`           | Y        | Workflow version (distinguishes from existing runs when changed)    |
-| `name`        | `string`           | N        | Workflow name (default: function name converted to underscore case) |
-| `schema`      | `StandardSchemaV1` | N        | Input validation schema (Zod, etc.)                                 |
-| `schedules`   | `Schedule[]`       | N        | Array of cron schedules                                             |
-| `retryPolicy` | `RetryPolicy`      | N        | Retry policy                                                        |
-
-### Workflow Function Parameters
-
-| Parameter | Type             | Description                               |
-| --------- | ---------------- | ----------------------------------------- |
-| `input`   | `Input`          | Input value passed when the workflow runs |
-| `step`    | `StepWrapper`    | Tool for defining/executing steps         |
-| `logger`  | `Logger`         | @logtape/logtape logger                   |
-| `version` | `string \| null` | Current workflow version                  |
-
-## Step
-
-An atomic unit of execution within a workflow. On failure, retry begins from that step.
-
-### step.define — Inline Function
-
-```typescript
-const result = await step
-  .define({ name: "fetch-data" }, async () => {
-    const data = await fetchSomething();
-    return data;
-  })
-  .run();
-```
-
-### step.get — Wrapping an Existing Method
-
-```typescript
-// Wrap a Model method as a Step
-const result = await step.get(MyModel, "processData").run(inputData);
-
-// Specify a custom name
-const result = await step.get({ name: "custom_step" }, MyService, "execute").run(params);
-```
-
-Overloads for `step.get`:
-
-- `step.get(object, methodName)` — Step name is the methodName converted to underscore case
-- `step.get({ name }, object, methodName)` — Step name specified directly
-
-### step.sleep — Durable Wait
-
-```typescript
-await step.sleep("wait-before-retry", "30m");
-await step.sleep("daily-delay", "1d");
-```
-
-The wait time is preserved even if the server restarts.
-
-**DurationString format:** `{number}{unit}` — e.g. `"5s"`, `"30m"`, `"2h"`, `"7d"`, `"1w"`, `"1y"`
-
-## Scheduling (cron)
-
-```typescript
-export const dailyReport = workflow(
-  {
-    version: "1",
-    schedules: [
-      {
-        expression: "0 9 * * *", // every day at 9am
-        name: "daily-report", // optional (default: workflowName[expression])
-        input: () => ({ date: new Date().toISOString() }), // optional
-      },
-    ],
-  },
-  async ({ input, step }) => {
-    // ...
-  },
-);
-```
-
-| Field        | Type                | Required | Description                                          |
-| ------------ | ------------------- | -------- | ---------------------------------------------------- |
-| `expression` | `string`            | Y        | cron expression                                      |
-| `name`       | `string`            | N        | Schedule name (default: `workflowName[expression]`)  |
-| `input`      | `Executable<Input>` | N        | Input value to pass on execution (function or value) |
-
-The timezone follows the `api.timezone` setting in `sonamu.config.ts`.
-
-## Retry Policy
-
-### Static Policy (Default)
-
-```typescript
-export const reliableTask = workflow(
-  {
-    version: "1",
-    retryPolicy: {
-      maxAttempts: 5, // maximum retry attempts (default: 5)
-      initialIntervalMs: 1000, // first retry wait time (default: 1000ms)
-      backoffCoefficient: 2, // wait time multiplier (default: 2)
-      maximumIntervalMs: 60000, // maximum wait time
-    },
-  },
-  async ({ step }) => {
-    // ...
-  },
-);
-```
-
-### Dynamic Policy
-
-```typescript
-retryPolicy: {
-  maxAttempts: 10,
-  shouldRetry: (error, attempt) => ({
-    shouldRetry: error.message !== "FATAL",
-    delayMs: attempt * 2000,
-  }),
-}
-```
-
-## sonamu.config.ts Configuration
-
-```typescript
-export default defineConfig({
-  tasks: {
-    enableWorker: true,
-    workerOptions: {
-      concurrency: 4, // concurrent execution count (default: CPU cores - 1)
-      usePubSub: true, // use DB pub/sub (default: true)
-      listenDelay: 500, // execution delay after pub/sub receive in ms (default: 500)
-    },
-    contextProvider: (defaultContext) => {
-      // build Context to use within workflows
-      return { ...defaultContext };
-    },
-  },
-});
-```
-
-| Option                      | Type               | Description                                        |
-| --------------------------- | ------------------ | -------------------------------------------------- |
-| `enableWorker`              | `boolean`          | Whether to enable Worker (use only in daemon mode) |
-| `workerOptions.concurrency` | `number`           | Number of concurrently executing tasks             |
-| `workerOptions.usePubSub`   | `boolean`          | Use PostgreSQL pub/sub                             |
-| `workerOptions.listenDelay` | `number`           | Execution delay after pub/sub receive (ms)         |
-| `contextProvider`           | `(ctx) => Context` | Context creation function when workflow runs       |
-
-## Manual Execution
-
-```typescript
-import { Sonamu } from "sonamu";
-
-// Run via WorkflowManager
-const handle = await Sonamu.workflowManager.run(
-  { name: "my-task", version: "1" },
-  { target: "manual" },
-);
-
-// Wait for result
-const result = await handle.result();
-```
-
-## File Placement
-
-```
-packages/api/src/application/
-├── {domain}/
-│   ├── {domain}.model.ts
-│   ├── {domain}.types.ts
-│   └── {domain}.workflow.ts    ← workflow file
-```
-
-Define with `workflow()` and export in the workflow file; the syncer will collect it automatically.
-
-## Architecture
-
-```
-Dev Server startup
-  → WorkflowManager initialization (BackendPostgres)
-  → Worker startup (when enableWorker: true)
-  → syncer collects .workflow.ts files
-  → registers via WorkflowManager.synchronize()
-  → cron schedules start automatically
-
-On HMR
-  → re-register workflows from changed files (synchronize)
-
-Execution flow
-  → run() called → workflow execution record created in DB
-  → Worker receives via pub/sub → steps executed sequentially
-  → checkpoint saved to DB on each step completion
-  → on failure: retry from that step according to retryPolicy
-  → on server restart: incomplete workflows recovered from DB and continue
-```