Using Services - 🌲 Sonamu

Learn how to call APIs type-safely using the generated Namespace Services.

Service Usage Overview

Namespace Calls

UserService.getUser() Concise syntax

Type Safe

Auto-completion Compile validation

Subset Support

Only needed fields Performance optimization

TanStack Query

useUser Hook Auto caching

Basic Usage

Service Import

Generated Services are exported as Namespaces from services.generated.ts.

// ✅ Correct import method
import { UserService, PostService } from "@/services/services.generated";

Benefits of single file import:

Consistency: All Services managed in one place
Easy import: No need to find file paths
Auto update: Auto-synced on pnpm generate
Clear naming: Grouped by Namespace, no conflicts

Basic API Calls

Call Service static functions directly.

import { UserService } from "@/services/services.generated";

// Get user (only basic info with Subset "A")
const user = await UserService.getUser("A", 123);
console.log(user.username); // Type safe!

// Update user
await UserService.updateProfile({
  username: "newname",
  bio: "Hello, World!",
});

Features:

Async call with await
Response is auto-parsed (handled inside fetch function)
Types fully guaranteed
Subset parameter required (for getUser, etc.)

Namespace-based structure: - ❌ Class instance: No need for new UserService() - ✅ Static function: Call UserService.getUser() directly - All functions work independently

Understanding the Subset System

Sonamu’s core feature, the Subset system.

// Subset "A": Basic info
const basicUser = await UserService.getUser("A", 123);
console.log(basicUser.id); // ✅ OK
console.log(basicUser.username); // ✅ OK
console.log(basicUser.bio); // ❌ Compile error (not in Subset A)

// Subset "B": Including bio
const userWithBio = await UserService.getUser("B", 123);
console.log(userWithBio.bio); // ✅ OK

// Subset "C": All fields
const fullUser = await UserService.getUser("C", 123);
console.log(fullUser.createdAt); // ✅ OK

Why use Subset:

Performance: Query only needed fields to reduce network cost
Type safety: Returns accurate type for each Subset
Explicitness: Clearly express what data is needed in code

Using in React

TanStack Query Hook (Recommended)

The easiest way is to use auto-generated TanStack Query Hooks.

import { UserService } from "@/services/services.generated";

function UserProfile({ userId }: { userId: number }) {
  // Use auto-generated Hook
  const { data: user, error, isLoading } = UserService.useUser("A", userId);

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  if (!user) return <div>User not found</div>;

  return (
    <div>
      <h1>{user.username}</h1>
      <p>{user.email}</p>
    </div>
  );
}

Benefits of TanStack Query Hooks:

Auto caching (reuses same userId)
Auto revalidation (on focus, reconnection)
Auto loading/error state management
Auto duplicate request removal

Function Component (useEffect)

You can also call directly without using Hooks.

import { useState, useEffect } from "react";
import { UserService } from "@/services/services.generated";
import type { User } from "@/services/services.generated";

function UserProfile({ userId }: { userId: number }) {
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    async function fetchUser() {
      try {
        setLoading(true);
        // Get all fields with Subset "C"
        const userData = await UserService.getUser("C", userId);
        setUser(userData);
      } catch (err) {
        setError(err instanceof Error ? err.message : "Failed to load user");
      } finally {
        setLoading(false);
      }
    }

    fetchUser();
  }, [userId]);

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;
  if (!user) return <div>User not found</div>;

  return (
    <div>
      <h1>{user.username}</h1>
      <p>{user.email}</p>
    </div>
  );
}

Recommended: Use TanStack Query Hooks when possible. They provide auto caching, revalidation, and state management, making code much more concise.

Event Handlers

Call APIs based on user actions.

import { useState } from "react";
import { UserService } from "@/services/services.generated";

function EditProfile({ userId }: { userId: number }) {
  const [username, setUsername] = useState("");
  const [bio, setBio] = useState("");
  const [saving, setSaving] = useState(false);

  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault();

    try {
      setSaving(true);

      await UserService.updateProfile({
        username,
        bio,
      });

      alert("Profile updated!");
    } catch (error) {
      alert("Failed to update profile");
      console.error(error);
    } finally {
      setSaving(false);
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        value={username}
        onChange={(e) => setUsername(e.target.value)}
        placeholder="Username"
      />

      <textarea
        value={bio}
        onChange={(e) => setBio(e.target.value)}
        placeholder="Bio"
      />

      <button type="submit" disabled={saving}>
        {saving ? "Saving..." : "Save"}
      </button>
    </form>
  );
}

Using Services in SSR

Sonamu supports SSR based on Vite + React. For SSR, use the SSR-specific Services automatically generated in queries.generated.ts.

What are SSR Services?

Separate from frontend Services (services.generated.ts), SSR-specific Services are automatically generated on the backend.

// api/src/application/queries.generated.ts (auto-generated)
import type { SSRQuery } from "sonamu/ssr";

export namespace UserService {
  // Returns SSRQuery object (no HTTP request)
  export const getUser = <T extends UserSubsetKey>(subset: T, id: number): SSRQuery =>
    createSSRQuery("UserModel", "findById", [subset, id], ["User", "getUser"]);

  export const me = (): SSRQuery => createSSRQuery("UserModel", "me", [], ["User", "me"]);
}

Using in registerSSR

Use these Services when registering SSR routes.

// api/src/ssr/routes.ts
import { registerSSR } from "sonamu/ssr";
import { UserService, CompanyService } from "../application/queries.generated";

// Company detail page SSR
registerSSR({
  path: "/companies/:companyId",
  preload: (params) => [
    // Call Service method → Returns SSRQuery object
    UserService.me(),
    CompanyService.getCompany("A", Number(params.companyId)),
  ],
});

Frontend Service vs SSR Service

Item	Frontend Service	SSR Service
File Location	`web/src/services/services.generated.ts`	`api/src/application/queries.generated.ts`
Return Value	`Promise<Data>` (HTTP request)	`SSRQuery` (object)
Used In	Browser (React components)	Backend (`registerSSR`)
HTTP Request	✅ Real API call	❌ Direct backend Model execution

// Frontend Service (browser)
const user = await UserService.getUser("A", 123); // HTTP GET /api/user/findById

// SSR Service (backend)
const query = UserService.getUser("A", 123); // Returns SSRQuery object
// → Sonamu directly executes UserModel.findById("A", 123)

Key Difference: SSR Services execute backend Model methods directly without HTTP requests, eliminating network overhead.

Learn More

For detailed information about SSR, see the following documents.

Data Preloading

Preload data on the server with registerSSR

SSR Setup

Understand the SSR system

Understanding the Service Creation Mechanism

Services are Namespace-based static function collections.

Services are Namespaces, Not Classes

// services.generated.ts (auto-generated)

// ❌ Not a class
// class UserService { ... }

// ✅ It's a Namespace
export namespace UserService {
  // Static functions
  export async function getUser<T extends UserSubsetKey>(
    subset: T,
    id: number,
  ): Promise<UserSubsetMapping[T]> {
    return fetch({
      method: "GET",
      url: `/api/user/getUser?${qs.stringify({ subset, id })}`,
    });
  }

  export async function save(spa: UserSaveParams[]): Promise<number[]> {
    return fetch({
      method: "POST",
      url: `/api/user/save`,
      data: { spa },
    });
  }

  // TanStack Query Hook
  export const useUser = <T extends UserSubsetKey>(subset: T, id: number) =>
    useQuery({
      queryKey: ["User", "getUser", subset, id],
      queryFn: () => getUser(subset, id),
    });
}

Namespace Characteristics:

Stateless: No instance creation needed
Static calls: Call UserService.getUser() directly
Type-safe: Full type inference via TypeScript Namespaces
Tree-shakable: Unused functions are excluded from the bundle

Services Have No Dependency Injection (DI)

Services are pure functions, so no dependencies are injected:

// ❌ No DI (not a class)
// new UserService(dependencies)

// ✅ Direct call
const user = await UserService.getUser("A", 123);

How is Context passed? Services pass Context via HTTP requests:

// Service internals (simplified)
export async function getUser(subset: string, id: number) {
  return fetch({
    method: "GET",
    url: `/api/user/getUser?subset=${subset}&id=${id}`,
    // Context is passed via HTTP headers
    headers: {
      Authorization: `Bearer ${getToken()}`,
      Cookie: document.cookie, // Session information
    },
  });
}

On the backend, Context is automatically extracted from the HTTP request:

// Backend Model
class UserModelClass extends BaseModelClass {
  @api({ httpMethod: "GET" })
  async getUser(subset: string, id: number) {
    // Context is automatically parsed from the HTTP request
    const context = Sonamu.getContext();

    console.log(context.user); // Authenticated user
    console.log(context.session); // Session information
    console.log(context.request.ip); // Client IP

    // Authorization checks possible
    if (!context.user) {
      throw new UnauthorizedException("Login is required");
    }

    return this.findById(id, [subset]);
  }
}

Service Creation Process

Creation Steps:

Backend: Write @api decorator on Model
Sonamu Sync: Run pnpm sonamu sync
Auto-generation: services.generated.ts file created
Namespace Functions: Each API method converted to Namespace function
Hook Generation: GET methods automatically generate useQuery Hooks

Where Are Model Instances?

Created directly in Server Components:

// Server Component
export default async function UserPage() {
  // ✅ Instantiate Model directly on the server
  const userModel = new UserModel();
  const user = await userModel.findById(1, ["A"]);

  return <div>{user.username}</div>;
}

Why is new UserModel() safe?

Models are stateless, so creating new instances each time is safe
The constructor only initializes Subset queries
Context is dynamically retrieved via Sonamu.getContext()

// Model internals
class UserModelClass extends BaseModelClass {
  constructor() {
    super("User", userSubsetQueries, userLoaderQueries);
    // No state stored
  }

  async findById(id: number, subsets: string[]) {
    // Context is dynamically retrieved here
    const context = Sonamu.getContext();

    // Execute DB query
    return this.getPuri("r").table("users").where("id", id).first();
  }
}

Service vs Model Comparison

Item	Service (Frontend)	Model (Backend)
Type	Namespace	Class Instance
Call Style	`UserService.getUser()`	`userModel.findById()`
State	Stateless	Stateless
Dependencies	None	BaseModelClass
Context	Passed via HTTP headers	`Sonamu.getContext()`
Usage Context	Client Component	Server Component / API
Creation	Auto-generated	Developer-written

Cautions when creating Model instances: 1. Server Components only: Models cannot be imported in Client Components 2. Create each time: Singleton pattern unnecessary (stateless) 3. Context access: Sonamu.getContext() automatically retrieves from request context

Recommended patterns: - Client Component: Use Service - Server Component: Use Model directly - API endpoint: @api decorator on Model

Client Components

Services can be freely used in Client Components.

// app/users/[id]/edit-button.tsx
"use client";

import { useState } from "react";
import { UserService } from "@/services/services.generated";

export function EditButton({ userId }: { userId: number }) {
  const [editing, setEditing] = useState(false);

  async function handleEdit() {
    setEditing(true);

    try {
      await UserService.updateProfile({
        username: "newname",
      });

      alert("Updated!");
    } catch (error) {
      alert("Failed!");
    } finally {
      setEditing(false);
    }
  }

  return (
    <button onClick={handleEdit} disabled={editing}>
      {editing ? "Saving..." : "Edit"}
    </button>
  );
}

Error Handling

SonamuError Handling

Handle errors from Service calls in a type-safe manner.

import { UserService } from "@/services/services.generated";
import { isSonamuError } from "@/lib/sonamu.shared";

async function updateUser() {
  try {
    await UserService.updateProfile({
      username: "newname",
    });
  } catch (error) {
    if (isSonamuError(error)) {
      // Sonamu error (type safe)
      console.log("Status:", error.code);
      console.log("Message:", error.message);

      // Zod validation errors
      error.issues.forEach((issue) => {
        console.log(`${issue.path.join(".")}: ${issue.message}`);
      });

      // Handle by HTTP status code
      if (error.code === 401) {
        // Auth error
        console.log("Please login");
      } else if (error.code === 403) {
        // Permission error
        console.log("Permission denied");
      } else if (error.code === 422) {
        // Validation error
        console.log("Invalid data:", error.issues);
      }
    } else {
      // General error
      console.log("Network error:", error);
    }
  }
}

Error Handling in React

import { isSonamuError } from "@/lib/sonamu.shared";

function EditProfile({ userId }: { userId: number }) {
  const [error, setError] = useState<string | null>(null);
  const [validationErrors, setValidationErrors] = useState<Record<string, string>>({});

  async function handleSubmit(data: any) {
    setError(null);
    setValidationErrors({});

    try {
      await UserService.updateProfile(data);
    } catch (err) {
      if (isSonamuError(err)) {
        setError(err.message);

        // Map Zod validation errors by field
        const fieldErrors: Record<string, string> = {};
        err.issues.forEach((issue) => {
          const field = issue.path.join(".");
          fieldErrors[field] = issue.message;
        });
        setValidationErrors(fieldErrors);
      } else {
        setError("An unexpected error occurred");
      }
    }
  }

  return (
    <div>
      {error && <div className="error-message">{error}</div>}

      <form onSubmit={(e) => {
        e.preventDefault();
        handleSubmit({/* data */});
      }}>
        <div>
          <input name="username" />
          {validationErrors.username && (
            <span className="error">{validationErrors.username}</span>
          )}
        </div>
      </form>
    </div>
  );
}

Advanced Patterns

Parallel Requests

Call multiple APIs simultaneously to improve performance.

import { UserService, PostService } from "@/services/services.generated";

async function loadUserDashboard(userId: number) {
  // ❌ Sequential execution (slow)
  const user = await UserService.getUser("A", userId);
  const posts = await PostService.getPostsByUser(userId);
  const comments = await PostService.getCommentsByUser(userId);

  return { user, posts, comments };
}

async function loadUserDashboardFast(userId: number) {
  // ✅ Parallel execution (fast)
  const [user, posts, comments] = await Promise.all([
    UserService.getUser("A", userId),
    PostService.getPostsByUser(userId),
    PostService.getCommentsByUser(userId),
  ]);

  return { user, posts, comments };
}

Performance comparison:

Sequential: 300ms + 200ms + 150ms = 650ms
Parallel: max(300ms, 200ms, 150ms) = 300ms

Subset Optimization

Choose appropriate Subset for the situation.

// List view: Only basic info
const users = await UserService.getUsers("A");

users.map((user) => (
  <div key={user.id}>
    {user.username} - {user.email}
  </div>
));

// Detail view: All info
const fullUser = await UserService.getUser("C", userId);

<div>
  <h1>{fullUser.username}</h1>
  <p>{fullUser.bio}</p>
  <p>Created: {fullUser.createdAt}</p>
</div>

TanStack Query Utilization

Conditional Fetching

function UserProfile({ userId }: { userId: number | null }) {
  const { data: user } = UserService.useUser(
    "A",
    userId!,
    { enabled: userId !== null } // Don't call if userId is null
  );

  if (!userId) return <div>Please select a user</div>;
  if (!user) return <div>Loading...</div>;

  return <div>{user.username}</div>;
}

Cache Invalidation

import { useQueryClient } from "@tanstack/react-query";
import { UserService } from "@/services/services.generated";

function EditProfile({ userId }: { userId: number }) {
  const queryClient = useQueryClient();

  async function handleUpdate(data: any) {
    await UserService.updateProfile(data);

    // Invalidate specific query
    queryClient.invalidateQueries(UserService.getUserQueryOptions("A", userId));

    // Or invalidate all User queries
    queryClient.invalidateQueries({
      queryKey: ["User"],
    });
  }
}

Prefetching

function UserList({ userIds }: { userIds: number[] }) {
  const queryClient = useQueryClient();

  // Preload on hover
  function handleMouseEnter(userId: number) {
    queryClient.prefetchQuery(
      UserService.getUserQueryOptions("A", userId)
    );
  }

  return (
    <ul>
      {userIds.map((id) => (
        <li
          key={id}
          onMouseEnter={() => handleMouseEnter(id)}
        >
          User {id}
        </li>
      ))}
    </ul>
  );
}

Practical Example

Complete CRUD Flow

import { useState } from "react";
import { UserService } from "@/services/services.generated";
import { isSonamuError } from "@/lib/sonamu.shared";

function UserManagement() {
  // List query (Subset A)
  const { data: users, refetch } = UserService.useUsers("A");

  // Create
  async function handleCreate(data: { username: string; email: string }) {
    try {
      await UserService.create(data);
      refetch(); // Refresh list
      alert("Created!");
    } catch (error) {
      if (isSonamuError(error)) {
        alert(error.message);
      }
    }
  }

  // Update
  async function handleUpdate(id: number, data: { username: string }) {
    try {
      await UserService.update(id, data);
      refetch();
      alert("Updated!");
    } catch (error) {
      if (isSonamuError(error)) {
        alert(error.message);
      }
    }
  }

  // Delete
  async function handleDelete(id: number) {
    if (!confirm("Are you sure?")) return;

    try {
      await UserService.delete(id);
      refetch();
      alert("Deleted!");
    } catch (error) {
      if (isSonamuError(error)) {
        alert(error.message);
      }
    }
  }

  return (
    <div>
      <h1>Users</h1>
      {users?.map((user) => (
        <div key={user.id}>
          {user.username}
          <button onClick={() => handleUpdate(user.id, { username: "new" })}>
            Edit
          </button>
          <button onClick={() => handleDelete(user.id)}>
            Delete
          </button>
        </div>
      ))}
    </div>
  );
}

Cautions

Cautions when using Services: 1. Never manually modify generated Service files (services.generated.ts) 2. Subset parameter required: Must specify subset for getUser, etc. 3. In Server Components, call backend model directly instead of Service 4. Use isSonamuError() type guard for error handling 5. TanStack Query Hooks should only be called inside components 6. await keyword required (all Service functions are async) 7. It’s a Namespace so no new needed: Call UserService.getUser() directly

Next Steps

How Services Work

Understanding auto-generation

TanStack Query Hook

Easier with React

Authentication

Authentication system

Error Handling

Error handling patterns

​Service Usage Overview

Namespace Calls

Type Safe

Subset Support

TanStack Query

​Basic Usage

​Service Import

​Basic API Calls

​Understanding the Subset System

​Using in React

​TanStack Query Hook (Recommended)

​Function Component (useEffect)

​Event Handlers

​Using Services in SSR

​What are SSR Services?

​Using in registerSSR

​Frontend Service vs SSR Service

​Learn More

Data Preloading

SSR Setup

​Understanding the Service Creation Mechanism

​Services are Namespaces, Not Classes

​Services Have No Dependency Injection (DI)

​Service Creation Process

​Where Are Model Instances?

​Service vs Model Comparison

​Client Components

​Error Handling

​SonamuError Handling

​Error Handling in React

​Advanced Patterns

​Parallel Requests

​Subset Optimization

​TanStack Query Utilization

​Conditional Fetching

​Cache Invalidation

​Prefetching

​Practical Example

​Complete CRUD Flow

​Cautions

​Next Steps

How Services Work

TanStack Query Hook

Authentication

Error Handling

Service Usage Overview

Basic Usage

Service Import

Basic API Calls

Understanding the Subset System

Using in React

TanStack Query Hook (Recommended)

Function Component (useEffect)

Event Handlers

Using Services in SSR

What are SSR Services?

Using in registerSSR

Frontend Service vs SSR Service

Learn More

Understanding the Service Creation Mechanism

Services are Namespaces, Not Classes

Services Have No Dependency Injection (DI)

Service Creation Process

Where Are Model Instances?

Service vs Model Comparison

Client Components

Error Handling

SonamuError Handling

Error Handling in React

Advanced Patterns

Parallel Requests

Subset Optimization

TanStack Query Utilization

Conditional Fetching

Cache Invalidation

Prefetching

Practical Example

Complete CRUD Flow

Cautions

Next Steps