Creating TypeScript Controllers

TypeScript
export const createEntityController = async (
  body: Namespace.Entity.CreateEntityParams,
): Promise<AxiosResponse<Namespace.Entity.Entity, any>> => {
  const url = '/api/entity/';
  const instance = genRequestInstance();

  try {
    const response = await instance.post(url, body);
    return response;
  } catch (error) {
    console.error('Erro na requisição:', error);
    return Promise.reject(error);
  }
};

1. Identify Parameters

   • Determine if URL parameters are needed (e.g., versao, id)
   • Identify the body/payload type required

2. Define Function Signature

   • URL parameters first (if any)
   • Body parameter last
   • Return type: Promise<AxiosResponse<EntityType, any>>

3. Build URL Path

   • Use template literals for dynamic parameters
   • Follow REST conventions: /api/module/entity/ or /api/module/param/entity/

4. Implement Request

   • Use genRequestInstance() for authentication
   • Use instance.post() for creation
   • Standard error handling pattern

5. Add JSDoc

   • Document all parameters
   • Document return type
   • Document potential errors

Example 1: Simple creation (no URL parameters) Input: Create a "user" controller Output:

TypeScript
/**
 * Creates a new user
 * @param body - User creation parameters
 * @returns Promise with created user data
 * @throws Error when request fails
 */
export const createUserController = async (
  body: User.CreateUserParams,
): Promise<AxiosResponse<User.User, any>> => {
  const url = '/api/user/';
  const instance = genRequestInstance();

  try {
    const response = await instance.post(url, body);
    return response;
  } catch (error) {
    console.error('Erro na requisição:', error);
    return Promise.reject(error);
  }
};

Example 2: Creation with URL parameter Input: Create a "task" controller within a "project" Output:

TypeScript
/**
 * Creates a new task within a project
 * @param projectId - ID of the project
 * @param body - Task creation parameters
 * @returns Promise with created task data
 * @throws Error when request fails
 */
export const createTaskController = async (
  projectId: Project.Project['id'],
  body: Task.CreateTaskParams,
): Promise<AxiosResponse<Task.Task, any>> => {
  const url = `/api/project/${projectId}/task/`;
  const instance = genRequestInstance();

  try {
    const response = await instance.post(url, body);
    return response;
  } catch (error) {
    console.error('Erro na requisição:', error);
    return Promise.reject(error);
  }
};