Enums - 🌲 Sonamu

Enum is an enumeration type that can only select from a predefined list of values. It provides type safety and makes it easy to configure selection options in user interfaces.

What is an Enum?

Enum defines a limited set of values to provide:

Type Safety

Prevents undefined value inputAutomatically converts to Union type in TypeScript

Auto UI Generation

Automatic selection list configurationImmediately usable in Select, ButtonSet components

Label Management

Separation of keys and display namesEasy multi-language support

Maintainability

Centralized managementOnly one place to modify when values change

Defining Enums

Defining in entity.json

Define as key-label pairs in the Entity’s enums section.

user.entity.json

{
  "id": "User",
  "props": [
    {
      "name": "role",
      "type": "enum",
      "id": "UserRole",
      "desc": "User role"
    },
    {
      "name": "status",
      "type": "enum",
      "id": "UserStatus",
      "desc": "Account status"
    }
  ],
  "enums": {
    "UserRole": {
      "admin": "Administrator",
      "normal": "Normal User",
      "guest": "Guest"
    },
    "UserStatus": {
      "active": "Active",
      "inactive": "Inactive",
      "suspended": "Suspended",
      "deleted": "Deleted"
    }
  }
}

Structure:

Enum ID: PascalCase (e.g., UserRole, PostStatus)
Key: lowercase, numbers, underscores (e.g., admin, draft_saved)
Label: Display text (e.g., “Administrator”, “Draft Saved”)

Defining in Sonamu UI

Navigate to Entity edit page

Select an Entity in Sonamu UI.

Scroll to Enums section

The Enums section is below Props, Indexes, Subsets.

Click Add Enum

Add a new Enum.Enter Enum ID:

Enter in PascalCase
Use {Entity} pattern to associate with Entity
- Example: $ModelRole → UserRole (auto-converted)

Add Enum values

Each Enum is displayed as a separate tab, add key-label pairs with the “Add Row” button.

Key: lowercase letters, numbers, underscores only
Label: Display name

Save

When you save the Entity, the Enum is saved together.

📸 Needed: Sonamu UI Enums section - multiple Enums displayed as tabs

Auto-Generated Code

When you define an Enum, Sonamu automatically generates the following:

1. Zod Schema

sonamu.generated.ts

import { z } from "zod";

// Enum schema
export const UserRole = z.enum(["admin", "normal", "guest"]);

// Enum labels
export const UserRoleLabels = {
  admin: "Administrator",
  normal: "Normal User",
  guest: "Guest",
} as const;

2. TypeScript Type

user.types.ts

import { UserRole } from "./sonamu.generated";

// Inferred as Union type
export type UserRole = z.infer<typeof UserRole>;
// Result: "admin" | "normal" | "guest"

3. Label Helper Function

sonamu.generated.ts

// Get label function
export function getUserRoleLabel(role: UserRole): string {
  return UserRoleLabels[role];
}

Using Enums

Using in Props

{
  "props": [
    {
      "name": "role",
      "type": "enum",
      "id": "UserRole",
      "desc": "User role",
      "dbDefault": "normal"
    }
  ]
}

Database:

Column type: text
Stored value: Key value (e.g., "admin")

TypeScript:

type User = {
  id: number;
  role: "admin" | "normal" | "guest"; // Union type
};

Using in API

import { UserRole } from "./user.types";

export class UserModel extends BaseModelClass {
  @api({ httpMethod: "POST" })
  async updateRole(userId: number, role: UserRole) {
    // role is type-safe
    await this.puri()
      .where("id", userId)
      .update({ role });
      
    return { success: true };
  }
}

import { UserRole } from "./sonamu.generated";

export const UserUpdateParams = z.object({
  id: z.number(),
  role: UserRole, // Auto-validated with Enum schema
});

export type UserUpdateParams = z.infer<typeof UserUpdateParams>;

Displaying Labels

import { getUserRoleLabel } from "./sonamu.generated";

const user = await UserModel.findById(1);
const roleLabel = getUserRoleLabel(user.role);
// "Administrator"

import { UserRoleLabels } from "@/services/sonamu.generated";

function UserBadge({ role }: { role: UserRole }) {
  return <span>{UserRoleLabels[role]}</span>;
  // "Administrator"
}

Common Enum Patterns

1. OrderBy Enum

Define sorting options.

{
  "enums": {
    "UserOrderBy": {
      "id-desc": "ID Newest First",
      "id-asc": "ID Oldest First",
      "created_at-desc": "Created At Newest First",
      "created_at-asc": "Created At Oldest First",
      "username-asc": "Name Order"
    }
  }
}

Usage:

async findAll(orderBy: UserOrderBy = "id-desc") {
  const [field, direction] = orderBy.split("-");
  return this.puri()
    .orderBy(field, direction as "asc" | "desc")
    .many();
}

2. SearchField Enum

Define searchable fields.

{
  "enums": {
    "UserSearchField": {
      "email": "Email",
      "username": "Name",
      "phone": "Phone"
    }
  }
}

Usage:

async search(field: UserSearchField, keyword: string) {
  return this.puri()
    .whereLike(field, `%${keyword}%`)
    .many();
}

3. Status Enum

Define statuses.

{
  "enums": {
    "PostStatus": {
      "draft": "Draft",
      "published": "Published",
      "archived": "Archived",
      "deleted": "Deleted"
    }
  }
}

Usage:

async publish(postId: number) {
  await this.puri()
    .where("id", postId)
    .update({ status: "published" });
}

4. Type/Category Enum

Define classifications.

{
  "enums": {
    "NotificationType": {
      "email": "Email",
      "sms": "SMS",
      "push": "Push Notification",
      "in_app": "In-App Notification"
    }
  }
}

Enum Array Type

You can store multiple Enum values as an array.

{
  "props": [
    {
      "name": "permissions",
      "type": "enum[]",
      "id": "Permission",
      "desc": "Permission list"
    }
  ],
  "enums": {
    "Permission": {
      "read": "Read",
      "write": "Write",
      "delete": "Delete",
      "admin": "Admin"
    }
  }
}

Database:

Column type: text[]
Stored value: ["read", "write"]

TypeScript:

type User = {
  id: number;
  permissions: ("read" | "write" | "delete" | "admin")[];
};

Usage:

// Check permission
function hasPermission(user: User, permission: Permission): boolean {
  return user.permissions.includes(permission);
}

// Grant permission
async grantPermission(userId: number, permission: Permission) {
  const user = await this.findById(userId);
  if (!user.permissions.includes(permission)) {
    await this.puri()
      .where("id", userId)
      .update({
        permissions: [...user.permissions, permission]
      });
  }
}

Using Enums in Frontend

Select Component

import { UserRoleSelect } from "@/components/UserRoleSelect";

function UserForm() {
  const [role, setRole] = useState<UserRole>("normal");
  
  return (
    <UserRoleSelect
      value={role}
      onChange={setRole}
    />
  );
}

import { UserRole, UserRoleLabels } from "@/services/sonamu.generated";

function UserForm() {
  return (
    <select>
      {UserRole.options.map(key => (
        <option key={key} value={key}>
          {UserRoleLabels[key]}
        </option>
      ))}
    </select>
  );
}

ButtonSet Component

import { UserStatusButtonSet } from "@/components/UserStatusButtonSet";

function StatusFilter() {
  const [status, setStatus] = useState<UserStatus | null>(null);
  
  return (
    <UserStatusButtonSet
      value={status}
      onChange={setStatus}
      allowNull // Allow deselection
    />
  );
}

Enum Validation

Zod automatically validates Enum values.

import { UserRole } from "./sonamu.generated";

export const UpdateRoleParams = z.object({
  userId: z.number(),
  role: UserRole, // Auto-validated
});

// When invalid value is input
UpdateRoleParams.parse({
  userId: 1,
  role: "invalid_role" // Error!
});

import { UserRole } from "./sonamu.generated";

// Allow only specific roles
export const AdminOnlyParams = z.object({
  role: UserRole.refine(
    (val) => val === "admin" || val === "superadmin",
    { message: "Admin permission required" }
  ),
});

Enum Naming Conventions

Recommended Patterns

Purpose	Pattern	Example
Entity status	`{Entity}Status`	`PostStatus`, `OrderStatus`
Entity type	`{Entity}Type`	`NotificationType`, `PaymentType`
Entity role	`{Entity}Role`	`UserRole`, `MemberRole`
Sort options	`{Entity}OrderBy`	`UserOrderBy`, `PostOrderBy`
Search fields	`{Entity}SearchField`	`UserSearchField`
Category	`{Entity}Category`	`ProductCategory`
Permission	`{Entity}Permission`	`UserPermission`

$Model Pattern

Use $Model to dynamically include the Entity name:

{
  "enums": {
    "$ModelRole": {
      "admin": "Administrator",
      "normal": "Normal"
    },
    "$ModelStatus": {
      "active": "Active",
      "inactive": "Inactive"
    }
  }
}

Conversion result:

User Entity → UserRole, UserStatus
Post Entity → PostRole, PostStatus

Cautions

Caution When Changing Enum ValuesChanging an Enum key that’s already stored in the database will cause mismatch with existing data.How to change:

Add new key
Data migration (old key → new key)
Remove old key

Key Naming RestrictionsEnum Keys can only use:

Lowercase letters (a-z)
Numbers (0-9)
Underscores (_)

Hyphens (-) cannot be used.

Labels Can Be Changed FreelyLabels are for display purposes, so they can be changed anytime. Only Keys are stored in the database.

Enum vs Separate Table

Criteria	Enum	Separate Table
Number of values	Few (< 20)	Many (> 20)
Change frequency	Rarely	Frequently
Additional info	Not needed	Needed (description, order, etc.)
Performance	Fast (no JOIN)	Slower (JOIN needed)
Recommended use	Status, role, type	Category, code tables

Enum use examples:

User roles (admin, user, guest)
Post status (draft, published, deleted)
Notification types (email, sms, push)

Separate table use examples:

Region list (Seoul, Busan, …)
Product categories (hierarchical structure)
Country codes (many additional info)

Next Steps

Field Types

Learn about other field types

Validation

Validate data with Zod

Frontend Components

Use generated components

API Development

API development using Enums

​What is an Enum?

Type Safety

Auto UI Generation

Label Management

Maintainability

​Defining Enums

​Defining in entity.json

​Defining in Sonamu UI

​Auto-Generated Code

​1. Zod Schema

​2. TypeScript Type

​3. Label Helper Function

​Using Enums

​Using in Props

​Using in API

​Displaying Labels

​Common Enum Patterns

​1. OrderBy Enum

​2. SearchField Enum

​3. Status Enum

​4. Type/Category Enum

​Enum Array Type

​Using Enums in Frontend

​Select Component

​ButtonSet Component

​Enum Validation

​Enum Naming Conventions

​Recommended Patterns

​$Model Pattern

​Cautions

​Enum vs Separate Table

​Next Steps

Field Types

Validation

Frontend Components

API Development

What is an Enum?

Defining Enums

Defining in entity.json

Defining in Sonamu UI

Auto-Generated Code

1. Zod Schema

2. TypeScript Type

3. Label Helper Function

Using Enums

Using in Props

Using in API

Displaying Labels

Common Enum Patterns

1. OrderBy Enum

2. SearchField Enum

3. Status Enum

4. Type/Category Enum

Enum Array Type

Using Enums in Frontend

Select Component

ButtonSet Component

Enum Validation

Enum Naming Conventions

Recommended Patterns

$Model Pattern

Cautions

Enum vs Separate Table

Next Steps