Controllers & Actions: Building Your API Logic

// src/features/user/controllers/user.controller.ts
import { igniter } from '@/igniter';
import { z } from 'zod';

export const userController = igniter.controller({
  /**
   * Optional name for the controller
   * Useful for documentation generation and MCP Server tool conversion
   */
  name: 'UserController',

  /**
   * The base path for all actions in this controller.
   * All action paths will be prefixed with `/users`.
   */
  path: '/users',

  /**
   * Optional description for documentation generation
   * Essential for OpenAPI spec generation and MCP Server AI agent integration
   */
  description: 'Handles all user-related operations including CRUD and authentication',

  /**
   * A collection of all API endpoints related to users.
   * Each key becomes an action name, each value defines the endpoint.
   */
  actions: {
    list: igniter.query({ /* ... */ }),
    getById: igniter.query({ /* ... */ }),
    create: igniter.mutation({ /* ... */ }),
    update: igniter.mutation({ /* ... */ }),
    delete: igniter.mutation({ /* ... */ }),
  },
});

const getUserById = igniter.query({
  /**
   * Optional action name for documentation and MCP Server integration
   */
  name: 'getUserById',
  
  /**
   * URL path - will be combined with controller path
   * Final URL: /users/:id (if controller path is '/users')
   */
  path: '/:id',
  
  /**
   * HTTP method for this endpoint
   */
  method: 'GET',
  
  /**
   * Query parameters validation using Zod
   */
  query: z.object({
    include: z.array(z.enum(['posts', 'profile'])).optional(),
    fields: z.string().optional(),
  }),
  
  /**
   * Optional description for API documentation
   */
  description: 'Retrieve a specific user by their ID with optional related data',
  
  /**
   * Tags for categorization and documentation
   */
  tags: ['users', 'read'],
  
  /**
   * Middleware stack - runs before the handler
   */
  use: [authMiddleware, rateLimitMiddleware],
  
  /**
   * The main business logic handler
   */
  handler: async (ctx) => {
    const { id } = ctx.params;              // URL parameters
    const { include, fields } = ctx.query; // Validated query params
    
    const user = await getUserFromDatabase(id, {
      include,
      fields: fields?.split(','),
    });
    
    if (!user) {
      throw new Error('User not found');
    }
    
    return { user };
  },
});

const createUser = igniter.mutation({
  /**
   * Optional action name for documentation and MCP Server tool conversion
   */
  name: 'createUser',
  
  /**
   * URL path for creating users
   */
  path: '/',
  
  /**
   * HTTP method for creation
   */
  method: 'POST',
  
  /**
   * Request body validation schema
   */
  body: z.object({
    name: z.string().min(2).max(50),
    email: z.string().email(),
    age: z.number().int().min(18).optional(),
    preferences: z.object({
      newsletter: z.boolean().default(false),
      theme: z.enum(['light', 'dark']).default('light'),
    }).optional(),
  }),
  
  /**
   * Documentation and metadata
   */
  description: 'Create a new user account with validated data',
  tags: ['users', 'create'],
  
  /**
   * Middleware for authentication and validation
   */
  use: [authMiddleware, validatePermissions('user:create')],
  
  /**
   * Handler with full type safety
   */
  handler: async (ctx) => {
    // ctx.body is fully typed based on the schema above
    const userData = ctx.body;
    
    // Check if user already exists
    const existingUser = await findUserByEmail(userData.email);
    if (existingUser) {
      throw new Error('User with this email already exists');
    }
    
    // Create the user
    const newUser = await createUserInDatabase({
      ...userData,
      createdAt: new Date(),
      updatedAt: new Date(),
    });
    
    // Return the created user (excluding sensitive data)
    return {
      user: {
        id: newUser.id,
        name: newUser.name,
        email: newUser.email,
        createdAt: newUser.createdAt,
      },
      message: 'User created successfully',
    };
  },
});

type HTTPMethod = 
  | 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' 
  | 'HEAD' | 'OPTIONS' | 'TRACE';

type QueryMethod = 'GET';  // Queries are typically GET requests
type MutationMethod = Exclude<HTTPMethod, 'GET'>;  // Mutations use other methods

// Complete example with all context features
const getUserById = igniter.query({
  path: '/users/:id',
  query: z.object({
    include: z.array(z.string()).optional(),
  }),
  handler: async (ctx) => {
    // URL Parameters (typed from path)
    const userId = ctx.request.params.id;
    
    // Query Parameters (validated)
    const includes = ctx.request.query?.include;
    
    // Headers
    const authToken = ctx.request.headers.get('authorization');
    
    // Cookies
    const sessionId = ctx.request.cookies.get('session-id');
    
    // Set response cookies
    ctx.response.setCookie('last-visited', new Date().toISOString(), {
      httpOnly: true,
      secure: true,
      maxAge: 86400
    });
    
    // Access application context
    const database = ctx.context.database;
    
    // Business logic
    const user = await database.user.findById(userId);
    
    // Return response using response processor
    return ctx.response.success({ user });
  },
});

// In src/features/user/controllers/user.controller.ts

import { igniter } from '@/igniter';
import { z } from 'zod';

export const userController = igniter.controller({
  path: '/users',
  actions: {
    /**
     * An action to list users.
     * Final Path: GET /users/
     */
    list: igniter.query({
      path: '/',

      // 1. Define and validate query parameters using Zod.
      // These are optional and have default values.
      query: z.object({
        page: z.coerce.number().int().positive().optional().default(1),
        limit: z.coerce.number().int().positive().optional().default(10),
      }),

      // 2. The main handler function.
      handler: async ({ request, context, response }) => {
        // `request.query` is fully typed by TypeScript as { page: number; limit: number; }
        // based on the Zod schema above. No manual parsing or validation needed.
        const { page, limit } = request.query;

        const skip = (page - 1) * limit;

        // Use the database client from the global context.
        const users = await context.database.user.findMany({
          take: limit,
          skip: skip,
        });

        const totalUsers = await context.database.user.count();

        // Use the response processor to return a structured, successful response.
        return response.success({
          users,
          pagination: {
            page,
            limit,
            total: totalUsers,
          },
        });
      },
    }),
  },
});

// In src/features/user/controllers/user.controller.ts

import { igniter } from '@/igniter';
import { z } from 'zod';
import { auth } from '@/features/auth/procedures/auth.procedure'; // Assuming an auth procedure exists

export const userController = igniter.controller({
  path: '/users',
  actions: {
    // ... (list action from above)

    /**
     * An action to create a new user.
     * Final Path: POST /users/
     */
    create: igniter.mutation({
      path: '/',
      method: 'POST',

      // 1. Apply the 'auth' procedure to protect this route.
      // This will run before the handler and can extend the context.
      use: [auth],

      // 2. Define and validate the request body using a Zod schema.
      body: z.object({
        name: z.string().min(2),
        email: z.string().email(),
      }),

      // 3. The main handler function.
      handler: async ({ request, context, response }) => {
        // `request.body` is fully typed as { name: string; email: string; }
        const { name, email } = request.body;

        // `context.user` is available and typed here because the `auth`
        // procedure added it to the context.
        const createdBy = context.user;
        context.logger.info(`User creation initiated by ${createdBy.email}`);

        const newUser = await context.database.user.create({
          data: { name, email },
        });

        // Use the `created` helper for a 201 Created status code.
        return response.created(newUser);
      },
    }),
  },
});