Entity Configuration

Learn how to configure entities with advanced options and handlers

Entity Configuration

Entities are the core building blocks of Frey. They define the structure of your data and the operations you can perform on it.

Basic Entity Structure

Required Properties

name: string

The entity name determines the route paths. For example:

  • name: "user" creates routes like /users, /users/:id
  • name: "product" creates routes like /products, /products/:id

schema: ZodObject

The Zod schema defines the structure and validation rules for your entity:

findAll: Handler

The findAll handler is required and handles GET /entity requests:

Optional Properties

customId: string

By default, Frey uses "id" as the identifier field. Use customId to specify a different field:

Handler Functions

All handler functions are optional except findAll. Each handler receives parameters and context:

findOne: Handler

Handles GET /entity/:id requests:

create: Handler

Handles POST /entity requests:

update: Handler

Handles PUT /entity/:id requests:

delete: Handler

Handles DELETE /entity/:id requests:

Handler Context

All handlers receive a context object with useful properties:

Using the Context

Advanced Configuration

Complex Schemas

You can define complex nested schemas:

Conditional Validation

Use Zod's conditional validation for complex business rules:

Best Practices

  1. Keep schemas focused: Each entity should represent a single concept
  2. Use descriptive names: Choose clear, descriptive names for your entities
  3. Validate early: Let Zod handle validation before your business logic
  4. Handle errors gracefully: Always handle potential errors in your handlers
  5. Use TypeScript: Leverage TypeScript for better development experience

Next Steps