scaffold - 🌲 Sonamu

The pnpm scaffold command auto-generates boilerplate code based on Entity definitions. It generates Model classes and test files in seconds, significantly reducing development time.

Basic Concept

Scaffold is an automation tool that converts Entities to code:

Entity-based: Understand types and structure from Entity definitions
Type-safe: TypeScript types are auto-generated
Consistent: All code follows the same pattern
Customizable: Freely customize after generation

Commands

model - Generate Model Class

Generate a Model class for an Entity.

pnpm scaffold model

An interactive prompt appears:

? Please select entity: (Use arrow keys)
❯ User
  Post
  Comment

Generated files: Generated code:

src/application/user/user.model.ts

import {
  api,
  asArray,
  BadRequestException,
  BaseModelClass,
  exhaustive,
  NotFoundException,
  type ListResult,
} from "sonamu";

import { SD } from "../../i18n/sd.generated";
import { UserSubsetKey, UserSubsetMapping } from "../sonamu.generated";
import { userLoaderQueries, userSubsetQueries } from "../sonamu.generated.sso";
import { UserListParams, UserSaveParams } from "./user.types";

/*
  User Model
*/
class UserModelClass extends BaseModelClass<
  UserSubsetKey,
  UserSubsetMapping,
  typeof userSubsetQueries,
  typeof userLoaderQueries
> {
  constructor() {
    super("User", userSubsetQueries, userLoaderQueries);
  }

  @api({ httpMethod: "GET", clients: ["axios", "tanstack-query"], resourceName: "User" })
  async findById<T extends UserSubsetKey>(subset: T, id: number): Promise<UserSubsetMapping[T]> {
    // ...
  }

  @api({ httpMethod: "GET", clients: ["axios", "tanstack-query"], resourceName: "Users" })
  async findMany<T extends UserSubsetKey, LP extends UserListParams>(
    subset: T,
    rawParams?: LP,
  ): Promise<ListResult<LP, UserSubsetMapping[T]>> {
    // handles id / search-keyword / orderBy, then calls executeSubsetQuery
  }

  @api({ httpMethod: "POST", clients: ["axios", "tanstack-mutation"] })
  async save(spa: UserSaveParams[]): Promise<number[]> {
    // ubRegister + transaction(ubUpsert)
  }

  @api({ httpMethod: "POST", clients: ["axios", "tanstack-mutation"], guards: ["admin"] })
  async del(ids: number[]): Promise<number> {
    // ...
  }
}

export const UserModel = new UserModelClass();

The real output contains full bodies for findById/findOne/findMany/save/del; they are elided above for brevity. When the Entity has a string primary key, id is generated as string.

model_test - Generate Test File

Generate a test file for a Model.

pnpm scaffold model_test

Generated files: Generated code:

src/application/user/user.model.test.ts

import { bootstrap, test } from "sonamu/test";
import { describe, expect, vi } from "vitest";

bootstrap(vi);
describe.skip("UserModelTest", () => {
  test("Query", async () => {
    expect(true).toBe(true);
  });
});

The generated test starts as describe.skip. Remove .skip once you have written real assertions.

View Scaffolding

Admin list and form components can also be generated from the CLI.

# Generate the list screen
pnpm scaffold view_list

# Generate the create/edit form
pnpm scaffold view_form

Generated files:

The same generators are available in the Scaffolding tab of Sonamu UI.

Generated Code Structure

Model Class

Generated Model classes have the following structure:

class UserModelClass extends BaseModelClass<
  UserSubsetKey,
  UserSubsetMapping,
  typeof userSubsetQueries,
  typeof userLoaderQueries
> {
  constructor() {
    super("User", userSubsetQueries, userLoaderQueries);
  }

  // Add methods here
  async findByEmail(email: string): Promise<User | null> {
    return this.getPuri("r").table("users").where("email", email).first();
  }
}

Auto-generated features:

✅ TypeScript types
✅ Subset/Loader query wiring
✅ BaseModelClass inheritance
✅ Basic CRUD methods (findById/findOne/findMany/save/del)

You need to add:

Business logic methods
Complex queries
Data validation
Relation loading

Test File

Generated test files include basic tests:

import { bootstrap, test } from "sonamu/test";
import { describe, expect, vi } from "vitest";

bootstrap(vi); // Sonamu init + per-test transaction wrapping
describe.skip("UserModelTest", () => {
  test("Query", async () => {
    expect(true).toBe(true);
  });
});

Extensible:

Add business logic tests
Edge case tests
Performance tests
Integration tests

Development Workflow

1. Define Entity

src/application/product/product.entity.json

{
  "id": "Product",
  "title": "Product",
  "table": "products",
  "props": [
    { "name": "id", "type": "integer", "desc": "ID" },
    { "name": "created_at", "type": "date", "desc": "Created at", "dbDefault": "CURRENT_TIMESTAMP" },
    { "name": "title", "type": "string", "length": 255, "desc": "Title" },
    { "name": "price", "type": "numeric", "precision": 10, "scale": 2, "desc": "Price" },
    {
      "type": "relation",
      "name": "category",
      "relationType": "BelongsToOne",
      "with": "Category",
      "onUpdate": "CASCADE",
      "onDelete": "CASCADE",
      "desc": "Category"
    }
  ],
  "indexes": [],
  "subsets": { "A": ["id", "created_at", "title", "price", "category.id"] },
  "enums": {
    "ProductOrderBy": { "id-desc": "Newest" },
    "ProductSearchField": { "id": "ID", "title": "Title" }
  }
}

2. Migration

# Create and apply migration
pnpm migrate run

3. Generate Model

# Generate Model class
pnpm scaffold model

# Select Entity: Product

4. Add Business Logic

src/application/product/product.model.ts

class ProductModelClass extends BaseModelClass<
  ProductSubsetKey,
  ProductSubsetMapping,
  typeof productSubsetQueries,
  typeof productLoaderQueries
> {
  constructor() {
    super("Product", productSubsetQueries, productLoaderQueries);
  }

  // Find products by category
  async findByCategory(categoryId: number) {
    return this.getPuri("r").table("products").where("category_id", categoryId).where("deleted_at", null);
  }

  // Find products by price range
  async findByPriceRange(min: number, max: number) {
    return this.getPuri("r").table("products").whereBetween("price", [min, max]);
  }
}

5. Generate Tests

# Generate test file
pnpm scaffold model_test

# Select Entity: Product

6. Write Tests

src/application/product/product.model.test.ts

import { bootstrap, test } from "sonamu/test";
import { describe, expect, vi } from "vitest";

import { ProductModel } from "./product.model";

bootstrap(vi);
describe("ProductModelTest", () => {
  test("findByCategory", async () => {
    const products = await ProductModel.findByCategory(1);
    expect(products.length).toBeGreaterThan(0);
    expect(products[0].category_id).toBe(1);
  });

  test("findByPriceRange", async () => {
    const products = await ProductModel.findByPriceRange(10000, 50000);
    products.forEach((product) => {
      expect(product.price).toBeGreaterThanOrEqual(10000);
      expect(product.price).toBeLessThanOrEqual(50000);
    });
  });
});

7. Add API

src/application/product/product.model.ts

class ProductModelClass extends BaseModelClass {
  @api({ httpMethod: "GET" })
  async findByCategory(categoryId: number) {
    const { qb } = this.getSubsetQueries("A");
    qb.where("category_id", categoryId);

    return this.executeSubsetQuery({
      subset: "A",
      qb,
      params: { num: 20, page: 1 },
    });
  }
}

Customization

Adding Model Methods

Add business logic to generated Models:

class UserModelClass extends BaseModelClass<
  UserSubsetKey,
  UserSubsetMapping,
  typeof userSubsetQueries,
  typeof userLoaderQueries
> {
  constructor() {
    super("User", userSubsetQueries, userLoaderQueries);
  }

  // Find user by email
  async findByEmail(email: string): Promise<User | null> {
    return this.getPuri("r").table("users").where("email", email).first();
  }

  // Find only active users
  async findActiveUsers() {
    return this.getPuri("r").table("users").where("is_active", true).where("deleted_at", null);
  }

  // User statistics
  async getUserStats(userId: number) {
    const [stats] = await this.getPuri("r")
      .table("users")
      .select({
        postCount: this.raw("COUNT(posts.id)"),
        commentCount: this.raw("COUNT(comments.id)"),
      })
      .leftJoin("posts", "posts.user_id", "users.id")
      .leftJoin("comments", "comments.user_id", "users.id")
      .where("users.id", userId)
      .groupBy("users.id");

    return stats;
  }
}

Extending Tests

Add more test cases:

describe("User Model - Extended", () => {
  test("findByEmail - existing email", async () => {
    const user = await UserModel.findByEmail("user1@example.com");
    expect(user).toBeDefined();
  });

  test("findByEmail - non-existing email", async () => {
    const user = await UserModel.findByEmail("notexist@example.com");
    expect(user).toBeNull();
  });

  test("findActiveUsers", async () => {
    const users = await UserModel.findActiveUsers();
    users.forEach((user) => {
      expect(user.is_active).toBe(true);
      expect(user.deleted_at).toBeNull();
    });
  });

  test("getUserStats", async () => {
    const stats = await UserModel.getUserStats(1);
    expect(stats.postCount).toBeGreaterThanOrEqual(0);
    expect(stats.commentCount).toBeGreaterThanOrEqual(0);
  });
});

Batch Generation for Multiple Entities

Using Scripts

# Generate Model for all Entities
for entity in User Post Comment Category; do
  echo $entity | pnpm scaffold model
done

Batch Test Generation

# Generate tests for all Models
for entity in User Post Comment Category; do
  echo $entity | pnpm scaffold model_test
done

Practical Tips

1. Complete Entity First

// ✅ Scaffold after Entity is fully defined
{
  "id": "User",
  "title": "User",
  "table": "users",
  "props": [
    // Define normal and relation props
  ],
  "indexes": [
    // Define indexes
  ],
  "subsets": {
    // Define response field sets
  },
  "enums": {
    // Define OrderBy / SearchField and friends
  }
}

2. Incremental Extension

// 1. Generate basic Model
pnpm scaffold model

// 2. Add simple methods first
async findById(id: number) { ... }

// 3. Add complex logic
async complexQuery() { ... }

// 4. Write tests
pnpm scaffold model_test

3. Follow Conventions

// ✅ Consistent naming
async findByEmail(email: string) { }     // find + By + Field
async findActiveUsers() { }               // find + Adjective + Entities
async getUserStats(userId: number) { }   // get + Noun + Type

// ✅ Consistent return types
Promise<User | null>      // Single record (nullable)
Promise<User[]>           // Multiple records
Promise<ListResult<UserListParams, User>> // Pagination

4. Git Management

# Commit generated files
git add src/application/user/user.model.ts
git add src/application/user/user.model.test.ts
git commit -m "Add User model and tests"

Troubleshooting

Regenerating Model

Problem: Want to regenerate Model Solution:

# Backup existing file
cp src/application/user/user.model.ts src/application/user/user.model.ts.bak

# Regenerate
pnpm scaffold model

# Restore necessary code

Syncing After Entity Change

Problem: Update Model after Entity change Solution:

# 1. Apply migration
pnpm migrate run

# 2. Update Model manually
# (Types sync automatically)

​Basic Concept

​Commands

​model - Generate Model Class

​model_test - Generate Test File

​View Scaffolding

​Generated Code Structure

​Model Class

​Test File

​Development Workflow

​1. Define Entity

​2. Migration

​3. Generate Model

​4. Add Business Logic

​5. Generate Tests

​6. Write Tests

​7. Add API

​Customization

​Adding Model Methods

​Extending Tests

​Batch Generation for Multiple Entities

​Using Scripts

​Batch Test Generation

​Practical Tips

​1. Complete Entity First

​2. Incremental Extension

​3. Follow Conventions

​4. Git Management

​Troubleshooting

​Regenerating Model

​Syncing After Entity Change

​Next Steps

Model

Testing

Basic Concept

Commands

model - Generate Model Class

model_test - Generate Test File

View Scaffolding

Generated Code Structure

Model Class

Test File

Development Workflow

1. Define Entity

2. Migration

3. Generate Model

4. Add Business Logic

5. Generate Tests

6. Write Tests

7. Add API

Customization

Adding Model Methods

Extending Tests

Batch Generation for Multiple Entities

Using Scripts

Batch Test Generation

Practical Tips

1. Complete Entity First

2. Incremental Extension

3. Follow Conventions

4. Git Management

Troubleshooting

Regenerating Model

Syncing After Entity Change

Next Steps