Compile-time Errors - 🌲 Sonamu

Learn how Sonamu detects API changes at compile time to prevent runtime errors in advance.

Compile-time Errors Overview

Instant Detection

On API changesCompile-time errors

Runtime Safety

Discover before deployProduction stability

IDE Integration

Red underlinesImmediate feedback

Safe Refactoring

Large-scale changesImpact range visibility

What are Compile-time Errors?

Problem: Errors Only Discovered at Runtime

In traditional development, API changes are only discovered at runtime.

// ❌ Field name changed in backend
// username → displayName

// Frontend (unaware of change)
function UserProfile({ userId }: { userId: number }) {
  const user = await fetchUser(userId);
  
  return (
    <div>
      {/* Runtime error! username field doesn't exist */}
      <h1>{user.username}</h1>
    </div>
  );
}

Problems with runtime errors:

Occurs in production: Users experience directly
Delayed discovery: Only discovered via QA or user reports
Hard to debug: Need to trace where problem occurred
Trust degradation: Service stability decreases

Solution: Compile-time Errors

Sonamu detects API changes immediately at compile time.

// ✅ Field name changed in backend
@api({ httpMethod: "GET" })
async getUser(): Promise<{
  user: {
    id: number;
    displayName: string; // username → displayName
    email: string;
  };
}> {
  // Implementation...
}

// Run pnpm generate → Service regenerated

// Frontend (compile-time error occurs!)
function UserProfile({ userId }: { userId: number }) {
  const { data } = UserService.useUser("A", userId);
  
  return (
    <div>
      {/* ❌ Compile error! Property 'username' does not exist */}
      <h1>{data.user.username}</h1>
      
      {/* ✅ After fix */}
      <h1>{data.user.displayName}</h1>
    </div>
  );
}

Benefits of compile-time errors:

✨ Instant discovery: IDE shows immediately while coding
✨ Fix before deploy: Resolve all issues before production deploy
✨ Impact range visibility: See all places affected by change
✨ Auto refactoring: Use IDE’s Rename feature

Error Detection Scenarios

1. Field Name Change

// Backend: username → displayName
@api({ httpMethod: "GET" })
async getUser(): Promise<{
  user: { id: number; displayName: string; }
}> {
  // Implementation...
}

// After pnpm generate
// Frontend: error at all user.username usage points
const { data } = await UserService.getUser("A", 123);
console.log(data.user.username); // ❌ Compile error

IDE error message:

Property 'username' does not exist on type '{ id: number; displayName: string; }'.
Did you mean 'displayName'?

2. Field Type Change

// Backend: changed age from number to string
@api({ httpMethod: "GET" })
async getUser(): Promise<{
  user: { id: number; age: string; } // number → string
}> {
  // Implementation...
}

// Frontend
const { data } = await UserService.getUser("A", 123);
const nextYear = data.user.age + 1; 
// ❌ Compile error: string + number

IDE error message:

Operator '+' cannot be applied to types 'string' and 'number'.

3. Required/Optional Change

// Backend: changed bio from required to optional
@api({ httpMethod: "GET" })
async getUser(): Promise<{
  user: {
    id: number;
    bio?: string; // string → string | undefined
  };
}> {
  // Implementation...
}

// Frontend
const { data } = await UserService.getUser("C", 123);
const bioLength = data.user.bio.length;
// ❌ Compile error: bio could be undefined

IDE error message:

Object is possibly 'undefined'.

Fix:

// ✅ Use optional chaining
const bioLength = data.user.bio?.length;

// ✅ Or null check
if (data.user.bio) {
  const bioLength = data.user.bio.length;
}

4. Field Deletion

// Backend: profile field removed
@api({ httpMethod: "GET" })
async getUser(): Promise<{
  user: {
    id: number;
    username: string;
    // profile field deleted
  };
}> {
  // Implementation...
}

// Frontend
const { data } = await UserService.getUser("C", 123);
console.log(data.user.profile.avatar);
// ❌ Compile error: Property 'profile' does not exist

5. Parameter Change

// Backend: parameter type changed
@api({ httpMethod: "GET" })
async searchUsers(query: {
  keyword: string;
  limit: number; // string → number
}): Promise<{ users: User[] }> {
  // Implementation...
}

// Frontend
await UserService.searchUsers({
  keyword: "john",
  limit: "10", // ❌ Compile error: string not assignable to number
});

IDE error message:

Type 'string' is not assignable to type 'number'.

6. Return Type Change

// Backend: changed from single object to array
@api({ httpMethod: "GET" })
async getPosts(): Promise<{
  posts: Post[]; // Post → Post[]
}> {
  // Implementation...
}

// Frontend
const { data } = await PostService.getPosts();
console.log(data.posts.title);
// ❌ Compile error: Property 'title' does not exist on type 'Post[]'

Fix:

// ✅ Handle array
data.posts.forEach((post) => {
  console.log(post.title);
});

Refactoring Support

Large-scale Changes are Safe

You can immediately identify all locations affected by API changes.

// Scenario: Major restructuring of User entity

// Backend (before)
@api({ httpMethod: "GET" })
async getUser(): Promise<{
  user: {
    id: number;
    name: string;
    email: string;
  };
}> {
  // ...
}

// Backend (after)
@api({ httpMethod: "GET" })
async getUser(): Promise<{
  user: {
    id: number;
    profile: {
      displayName: string;
      contactEmail: string;
    };
  };
}> {
  // ...
}

After running pnpm generate: All error locations are displayed in IDE:

src/components/UserProfile.tsx:15 - Property 'name' does not exist
src/components/UserCard.tsx:8 - Property 'name' does not exist
src/pages/users/[id].tsx:42 - Property 'email' does not exist
... (23 locations total)

Fix process:

Check all errors in IDE’s “Problems” panel
Visit each location and fix to match new structure
When all errors are resolved, compilation succeeds
Deploy safely

Leverage IDE’s Auto Refactoring

You can utilize TypeScript’s powerful refactoring features. Example: Batch Field Name Change

Check type definition in Service file
Position cursor on field name
F2 (Rename Symbol) or right-click → Rename
Enter new name
All usages are automatically changed

// ✅ Batch change username → displayName
// IDE automatically changes throughout project

// Before
data.user.username

// After (auto-changed)
data.user.displayName

Practical Workflow

1. Backend API Change

// backend/models/user.model.ts
@api({ httpMethod: "GET" })
async getProfile(): Promise<{
  user: {
    id: number;
    displayName: string; // Changed: username → displayName
    email: string;
  };
}> {
  // Implementation...
}

2. Service Regeneration

pnpm generate

Output:

✓ Analyzing API methods...
✓ Generating services.generated.ts...
✓ Generating types...
✓ Done!

3. TypeScript Compile

pnpm tsc --noEmit

Output (error occurs):

src/components/UserProfile.tsx:15:23 - error TS2339: 
Property 'username' does not exist on type '{ id: number; displayName: string; email: string; }'.

15     <h1>{data.user.username}</h1>
                      ~~~~~~~~

src/components/UserCard.tsx:8:35 - error TS2339: 
Property 'username' does not exist on type '{ id: number; displayName: string; email: string; }'.

8   const name = user.username;
                      ~~~~~~~~

Found 2 errors.

4. Fix Errors

// src/components/UserProfile.tsx
- <h1>{data.user.username}</h1>
+ <h1>{data.user.displayName}</h1>

// src/components/UserCard.tsx
- const name = user.username;
+ const name = user.displayName;

5. Re-verify

pnpm tsc --noEmit

Output (success):

✓ No errors found!

6. Deploy Safely

All type errors are resolved, so you can deploy safely.

CI/CD Integration

Add TypeScript Check to CI

# .github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  typecheck:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v2
      
      - name: Setup Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '22'
      
      - name: Install dependencies
        run: pnpm install
      
      - name: Generate Services
        run: pnpm generate
      
      - name: TypeScript Check
        run: pnpm tsc --noEmit

Benefits:

Auto-detect type errors in Pull Requests
Block merge if type errors exist
Ensure code quality across the team

Best Practices

1. Regular Service Regeneration

# When starting development
pnpm generate

# After backend changes
pnpm generate

# After pull
pnpm generate

2. Pre-commit Hook Setup

// package.json
{
  "husky": {
    "hooks": {
      "pre-commit": "pnpm tsc --noEmit"
    }
  }
}

Blocks commit if type errors exist.

3. VSCode Settings

// .vscode/settings.json
{
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true,
  "editor.codeActionsOnSave": {
    "source.fixAll": true
  }
}

4. Don’t Ignore Type Errors

// ❌ Ignoring type error (dangerous!)
// @ts-ignore
console.log(data.user.username);

// ✅ Correct fix
console.log(data.user.displayName);

Never use @ts-ignore. Type errors indicate real problems.

Understanding Error Messages

Common Error Messages

1. Property does not exist

Property 'username' does not exist on type 'User'.

→ Field was deleted or renamed 2. Type is not assignable

Type 'string' is not assignable to type 'number'.

→ Type was changed 3. Object is possibly undefined

Object is possibly 'undefined'.

→ Changed from required to optional 4. Cannot find name

Cannot find name 'UserService'.

→ Service not regenerated or import missing 5. Expected N arguments, but got M

Expected 2 arguments, but got 1.

→ API parameters added/removed

Cautions

Cautions when handling compile-time errors:

pnpm generate required: Always run after API changes
No @ts-ignore: Don’t ignore type errors
No any type: Breaks type safety
Fix all errors: Even one left can cause runtime error
CI/CD integration: Set up auto type checking

Next Steps

API Type Inference

Understanding type inference

Shared Types

Type file structure

Using Services

Service usage

Testing

Writing tests

Get Started

Core Concepts

Database

API Development

Frontend Integration

Testing

Advanced Features

Tools & CLI

Configuration

API Reference

Troubleshooting

FAQ

​Compile-time Errors Overview

Instant Detection

Runtime Safety

IDE Integration

Safe Refactoring

​What are Compile-time Errors?

​Problem: Errors Only Discovered at Runtime

​Solution: Compile-time Errors

​Error Detection Scenarios

​1. Field Name Change

​2. Field Type Change

​3. Required/Optional Change

​4. Field Deletion

​5. Parameter Change

​6. Return Type Change

​Refactoring Support

​Large-scale Changes are Safe

​Leverage IDE’s Auto Refactoring

​Practical Workflow

​1. Backend API Change

​2. Service Regeneration

​3. TypeScript Compile

​4. Fix Errors

​5. Re-verify

​6. Deploy Safely

​CI/CD Integration

​Add TypeScript Check to CI

​Best Practices

​1. Regular Service Regeneration

​2. Pre-commit Hook Setup

​3. VSCode Settings

​4. Don’t Ignore Type Errors

​Understanding Error Messages

​Common Error Messages

​Cautions

​Next Steps

API Type Inference

Shared Types

Using Services

Testing

Compile-time Errors Overview

What are Compile-time Errors?

Problem: Errors Only Discovered at Runtime

Solution: Compile-time Errors

Error Detection Scenarios

1. Field Name Change

2. Field Type Change

3. Required/Optional Change

4. Field Deletion

5. Parameter Change

6. Return Type Change

Refactoring Support

Large-scale Changes are Safe

Leverage IDE’s Auto Refactoring

Practical Workflow

1. Backend API Change

2. Service Regeneration

3. TypeScript Compile

4. Fix Errors

5. Re-verify

6. Deploy Safely

CI/CD Integration

Add TypeScript Check to CI

Best Practices

1. Regular Service Regeneration

2. Pre-commit Hook Setup

3. VSCode Settings

4. Don’t Ignore Type Errors

Understanding Error Messages

Common Error Messages

Cautions

Next Steps