sonamu 0.10.7 → 0.10.9

package/src/skills/sonamu-testing/references/quick-start.md

@@ -1,285 +0,0 @@
-# Quick Start — Getting Started with Tests Quickly
-
-
-**Prerequisites**: scaffolding completed, nullable field handling in types.ts completed
-
-### Step 1: Extend test-helpers.ts
-
-```typescript
-// packages/api/src/application/__tests__/test-helpers.ts
-
-import { User, UserSaveParams } from "../user/user.types";
-import { Post, PostSaveParams } from "../post/post.types";
-import { Comment, CommentSaveParams } from "../comment/comment.types";
-import UserModel from "../user/user.model";
-import PostModel from "../post/post.model";
-import CommentModel from "../comment/comment.model";
-
-// User helper
-export async function createTestUser(params?: Partial<UserSaveParams>): Promise<number> {
-  const user: UserSaveParams = {
-    email: `test-${Date.now()}@example.com`,
-    name: "Test User",
-    ...params,
-  };
-  const [id] = await UserModel.save([user]);
-  return id;
-}
-
-// User with dependencies (dependency chain)
-export async function createTestUserWithDeps() {
-  const userId = await createTestUser();
-  return { userId };
-}
-
-// Post helper
-export async function createTestPost(
-  authorId: number,
-  params?: Partial<PostSaveParams>,
-): Promise<number> {
-  const post: PostSaveParams = {
-    author_id: authorId,
-    title: "Test Post",
-    content: "Test content",
-    ...params,
-  };
-  const [id] = await PostModel.save([post]);
-  return id;
-}
-
-// Post with dependencies
-export async function createTestPostWithDeps() {
-  const { userId } = await createTestUserWithDeps();
-  const postId = await createTestPost(userId);
-  return { userId, postId };
-}
-
-// Comment helper
-export async function createTestComment(
-  postId: number,
-  authorId: number,
-  params?: Partial<CommentSaveParams>,
-): Promise<number> {
-  const comment: CommentSaveParams = {
-    post_id: postId,
-    author_id: authorId,
-    content: "Test comment",
-    ...params,
-  };
-  const [id] = await CommentModel.save([comment]);
-  return id;
-}
-
-// Comment with dependencies
-export async function createTestCommentWithDeps() {
-  const { userId, postId } = await createTestPostWithDeps();
-  const commentId = await createTestComment(postId, userId);
-  return { userId, postId, commentId };
-}
-```
-
-**CRITICAL patterns**:
-
-- `createTestX()`: basic creation helper (overridable via params)
-- `createTestXWithDeps()`: helper that automatically handles dependencies (creates all required data together)
-- FK fields use the `_id` suffix (`author_id`, `post_id`)
-- Returns: primarily returns ID; WithDeps returns an object with multiple IDs
-
-**CRITICAL: All required fields must be included!**
-
-Sonamu's `ubUpsert` uses PostgreSQL's `ON CONFLICT ... DO UPDATE` query.
-Even for updates, **all required fields (fields with NOT NULL constraints)** must be included.
-
-When required fields are missing:
-
-```typescript
-// BAD - missing required field content
-const post: PostSaveParams = {
-  author_id: authorId,
-  title: "Test",
-  // content missing! → ubUpsert ON CONFLICT UPDATE attempts to set NULL → DB error
-};
-// Error: null value in column "content" violates not-null constraint
-```
-
-### Distinguishing Required vs Optional Fields
-
-**1. Check entity.json**
-
-```json
-// post.entity.json
-{
-  "props": [
-    { "name": "id", "type": "integer" }, // auto-generated - exclude
-    { "name": "title", "type": "string", "length": 255 }, // required! (no nullable)
-    { "name": "content", "type": "string" }, // required! (no nullable)
-    { "name": "category", "type": "string", "nullable": true }, // optional (nullable)
-    { "name": "author_id", "type": "integer" }, // required! (FK, no nullable)
-    { "name": "view_count", "type": "integer", "dbDefault": "0" }, // required but has DB default
-    { "name": "created_at", "type": "date", "dbDefault": "CURRENT_TIMESTAMP" } // automatic
-  ]
-}
-```
-
-**Required fields**: Fields **without** `nullable: true`
-
-- `title`, `content`, `author_id`
-- **Must** provide default values in test-helpers.ts
-
-**Optional fields**: Fields **with** `nullable: true`
-
-- `category`
-- Can be omitted in test-helpers.ts
-
-**Excluded fields**:
-
-- `id`: auto-increment (auto-generated on save)
-- `created_at`: automatically set by dbDefault
-- `view_count`: automatically set by dbDefault="0"
-
-**2. Write test-helpers.ts**
-
-```typescript
-export async function createTestPost(
-  authorId: number,
-  params?: Partial<PostSaveParams>,
-): Promise<number> {
-  const post: PostSaveParams = {
-    // Required fields must be included (fields without nullable)
-    author_id: authorId,
-    title: "Test Post", // required!
-    content: "Test content", // required!
-
-    // Optional fields can be omitted (fields with nullable: true)
-    // category: null,  // can be omitted
-
-    // Fields with dbDefault can also be omitted
-    // view_count: 0,  // can be omitted since dbDefault="0"
-
-    ...params, // allow override
-  };
-  const saved = await PostModel.save(post);
-  return saved.id;
-}
-```
-
-**Rule summary**:
-
-1. Fields without `nullable: true` in entity.json = required fields
-2. Required fields **must** have default values in test-helpers.ts
-3. `id`, `created_at`, fields with `dbDefault` can be excluded
-4. Required fields are also needed for ubUpsert's ON CONFLICT UPDATE
-
-### Step 2: Write the test file
-
-```typescript
-// packages/api/src/application/post/__tests__/post.test.ts
-
-import { bootstrap } from "sonamu";
-import { describe, test, expect, vi } from "vitest";
-import PostModel from "../post.model";
-import { createTestPostWithDeps } from "../../__tests__/test-helpers";
-
-bootstrap(vi); // CRITICAL: required!
-
-describe("PostModel", () => {
-  describe("A. Create", () => {
-    test("create post", async () => {
-      const { userId, postId } = await createTestPostWithDeps();
-
-      const post = await PostModel.findById(postId, ["A"]);
-      expect(post.id).toBe(postId);
-      expect(post.author_id).toBe(userId);
-    });
-  });
-
-  describe("B. Read", () => {
-    test("findById - Subset A", async () => {
-      const { postId } = await createTestPostWithDeps();
-
-      const post = await PostModel.findById(postId, ["A"]);
-      expect(post.id).toBe(postId);
-      expect(post).toHaveProperty("title");
-      expect(post).toHaveProperty("content");
-    });
-
-    test("findMany - list query", async () => {
-      await createTestPostWithDeps();
-      await createTestPostWithDeps();
-
-      const { rows } = await PostModel.findMany({ num: 10 });
-      expect(rows.length).toBeGreaterThanOrEqual(2);
-    });
-  });
-
-  describe("C. Update", () => {
-    test("update post", async () => {
-      const { postId } = await createTestPostWithDeps();
-
-      await PostModel.save([
-        {
-          id: postId,
-          title: "Updated Title",
-        },
-      ]);
-
-      const updated = await PostModel.findById("A", postId);
-      expect(updated.title).toBe("Updated Title");
-    });
-  });
-
-  describe("D. Delete", () => {
-    test("delete post", async () => {
-      const { postId } = await createTestPostWithDeps();
-
-      await PostModel.del(postId);
-
-      const post = await PostModel.findById(postId, ["A"]);
-      expect(post).toBeNull();
-    });
-  });
-
-  describe("E. Business Logic", () => {
-    test("full process from post creation to adding a comment", async () => {
-      // 1. create post
-      const { userId, postId } = await createTestPostWithDeps({
-        title: "New Post",
-        content: "Content",
-      });
-
-      // 2. another user writes a comment
-      const commenterId = await createTestUser();
-      const commentId = await createTestComment(postId, commenterId, {
-        content: "Great post!",
-      });
-
-      // 3. fetch post (with comments)
-      const post = await PostModel.findById(postId, ["A"]);
-      expect(post.comments).toHaveLength(1);
-      expect(post.comments[0].id).toBe(commentId);
-    });
-  });
-});
-```
-
-**Pattern summary**:
-
-- `bootstrap(vi)` call is required
-- `describe` + `test` pattern (order: A. Create, B. Read, C. Update, D. Delete, E. Business Logic)
-- Use `createTestXWithDeps()` helper to automatically resolve dependencies
-- The Business Logic section is the most important! (implements real business scenarios)
-
-### Step 3: Run tests
-
-```bash
-# Start dev server if it's down
-pnpm sonamu dev
-
-# Tests during development (default)
-pnpm sonamu test
-pnpm sonamu test user.model
-```
-
-**Done!** See the sections below for detailed information.
-
----

package/src/skills/sonamu-testing/references/type-safety.md

@@ -1,172 +0,0 @@
-# TypeScript Type Safety in Tests
-
-## TypeScript Type Safety
-
-### Optional Chaining Required When Indexing Arrays
-
-When accessing a property after indexing into an array, you must use optional chaining (`?.`).
-
-**Reason:**
-
-- Array indexing (`array[0]`, `array[1]`, etc.) can always return `undefined`
-- TypeScript infers the type of `array[0]` as `T | undefined`
-- Accessing a property without optional chaining causes a compile error
-
-**Wrong:**
-
-```typescript
-// Type error: Object is possibly 'undefined'
-expect(list.rows[0].title).toBe("test");
-expect(searchResults.rows[0].name).toContain("keyword");
-```
-
-**Correct:**
-
-```typescript
-// Use optional chaining
-expect(list.rows[0]?.title).toBe("test");
-expect(searchResults.rows[0]?.name).toContain("keyword");
-
-// Or verify existence first, then access
-expect(list.rows.length).toBeGreaterThanOrEqual(1);
-expect(list.rows[0].title).toBe("test"); // now safe
-```
-
-### Recommended Patterns
-
-When accessing array elements in test code:
-
-**Pattern 1: Use optional chaining**
-
-```typescript
-const result = await Model.findMany("A", { num: 10, page: 1 });
-expect(result.rows[0]?.field).toBe(expectedValue);
-```
-
-**Pattern 2: Verify length, then access**
-
-```typescript
-const result = await Model.findMany("A", { num: 10, page: 1 });
-expect(result.rows.length).toBeGreaterThanOrEqual(1);
-expect(result.rows[0].field).toBe(expectedValue); // type-safe
-```
-
-**Pattern 3: Optional chaining required when using find()**
-
-```typescript
-const list = await Model.findMany("A", { num: 10, page: 1 });
-const item = list.rows.find((r) => r.id === targetId);
-expect(item?.field).toBe(expectedValue); // find() can return undefined
-```
-
-### General Rules
-
-- Property access after array indexing: `array[0]?.property`
-- Results of `find()`, `filter()[0]`, etc.: always use `?.`
-- Nested object access: `obj.nested?.deep?.property`
-- Non-null assertion (`!`) only when certain
-
-## Model Basic Methods (Test Targets)
-
-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) |
-
-**Note:** It's `del`, not `delete`. This avoids JavaScript reserved words.
-
-
-## Type Safety Notes
-
-### Zod Import Method
-
-**CRITICAL: Always use regular imports when importing Zod in test files.**
-
-```typescript
-// CORRECT - in test files
-import { z } from "zod";
-import { describe, expect, vi } from "vitest";
-
-// WRONG - runtime error when using type import
-import type { z } from "zod"; // error when test runs!
-```
-
-**Reason:** Because `z.infer<>` and Zod schemas are used directly in tests, the Zod object is needed at runtime.
-
-**Where this applies:**
-
-- `*.model.test.ts` - all test files
-- `test-helpers.ts` - helper files that use Zod schemas
-
-### Checking partial Settings in SaveParams
-
-When testing `Model.save()`, you must check the `SaveParams` partial settings in `*.types.ts`:
-
-```typescript
-// user.types.ts
-import { z } from "zod"; // regular import in types files too
-import { UserBaseSchema } from "../sonamu.generated";
-
-export const UserSaveParams = UserBaseSchema.partial({
-  id: true, // auto-generated
-  created_at: true, // auto-generated
-  updated_at: true, // auto-generated
-});
-export type UserSaveParams = z.infer<typeof UserSaveParams>;
-```
-
-### Nullable Field Handling Pattern
-
-**→ See "Tasks to Do Immediately After Entity Creation" section above** (partial + extend + nullish pattern)
-
-### Use Nullish Coalescing
-
-Nullish coalescing is required when a variable can be of type `T | undefined`:
-
-```typescript
-// WRONG: userId may be number | undefined
-const user = await UserModel.findById("A", userId);
-
-// CORRECT: guard against undefined with nullish coalescing
-const user = await UserModel.findById("A", userId ?? 0);
-```
-
-Especially be careful when using IDs created in a previous step:
-
-```typescript
-const [userId] = await UserModel.save([{ ... }]);
-
-// WRONG: userId is number | undefined
-const user = await UserModel.findById("A", userId);
-
-// CORRECT:
-const user = await UserModel.findById("A", userId ?? 0);
-```
-
-### SaveParams Import Location
-
-SaveParams types are exported from each entity's types.ts, not from sonamu.generated.
-
-**Wrong:**
-
-```typescript
-// test-helpers.ts
-import type { UserSaveParams, TaskSaveParams } from "../application/sonamu.generated"; // WRONG
-```
-
-**Correct:**
-
-```typescript
-// test-helpers.ts
-import type { UserSaveParams } from "../application/user/user.types";
-import type { TaskSaveParams } from "../application/task/task.types";
-```
-
-**Reason:**
-
-- sonamu.generated only exports BaseSchema and BaseListParams
-- SaveParams is defined with BaseSchema.partial() in each entity's types.ts