@forgepack/request 1.0.5 → 1.0.6

package/dist/services/crud.d.ts

@@ -1,87 +1,127 @@
 import { AxiosInstance } from 'axios';
 import { ErrorMessage } from '../types/error';
 import { Search } from '../types/request';
+import { Page } from '../types/response';
 /**
- * Cria um novo registro na API
+ * Creates a new record in the API via POST request
  *
- * @template T - Tipo do objeto a ser criado
- * @param api - Instância do Axios configurada
- * @param url - Endpoint da API (sem barra inicial)
- * @param object - Dados do objeto a ser criado
- * @returns Promise com dados criados ou array de erros
+ * @template T - Type of object to be created
+ * @param {AxiosInstance} api - Configured Axios instance with authentication
+ * @param {string} url - API endpoint path (without leading slash, e.g., 'users')
+ * @param {T} object - Object data to be created
+ * @returns {Promise<T | ErrorMessage[]>} Promise resolving to created data or array of errors
+ *
+ * @throws {never} Never throws - all errors are caught and returned as ErrorMessage[]
  *
  * @example
  * ```typescript
- * const result = await create(api, 'users', { name: 'João', email: 'joao@exemplo.com' })
+ * // Create a user
+ * const result = await create(api, 'users', { name: 'John Snow', email: 'john@example.com', role: 'USER' })
  * ```
  */
-export declare const create: <T>(api: AxiosInstance, url: string, object: T) => Promise<any>;
+export declare const create: <T>(api: AxiosInstance, url: string, object: T) => Promise<T | ErrorMessage[]>;
 /**
- * Cria múltiplos registros de uma vez na API
+ * Creates multiple records at once in the API via batch POST request
+ *
+ * @template T - Type of objects to be created
+ * @param {AxiosInstance} api - Configured Axios instance with authentication
+ * @param {string} url - API endpoint path (without leading slash, e.g., 'users')
+ * @param {T[]} object - Array of objects to be created
+ * @returns {Promise<T | ErrorMessage[]>} Promise resolving to created data or array of errors
+ *
+ * @throws {never} Never throws - all errors are caught and returned as ErrorMessage[]
+ *
+ * @example
+ * ```typescript
+ * // Create multiple users at once
+ * const users = [
+ *   { name: 'John Snow', email: 'john@example.com' },
+ *   { name: 'Jane Smith', email: 'jane@example.com' },
+ *   { name: 'Bob Johnson', email: 'bob@example.com' }
+ * ]
  *
- * @template T - Tipo dos objetos a serem criados
- * @param api - Instância do Axios configurada
- * @param url - Endpoint da API (sem barra inicial)
- * @param object - Array de objetos a serem criados
- * @returns Promise com dados criados ou array de erros
+ * const result = await createAll(api, 'users', users)
+ * ```
  */
-export declare const createAll: <T>(api: AxiosInstance, url: string, object: T[]) => Promise<ErrorMessage[] | T>;
+export declare const createAll: <T>(api: AxiosInstance, url: string, object: T[]) => Promise<T | ErrorMessage[]>;
 /**
- * Busca/recupera registros da API com suporte a paginação e busca
+ * Retrieves records from the API with optional pagination, search, and sorting support
+ *
+ * This function delegates to `fetchPage` for paginated requests and handles
+ * unpaginated retrieval directly.
  *
- * Comportamentos:
- * - Sem search: busca todos os registros
- * - Com page/size: busca paginada
- * - Com sort: busca paginada e ordenada
+ * Behaviors based on parameters:
+ * - Without search: retrieves all records
+ * - With page/size: paginated search
+ * - With sort: paginated and sorted search
  *
- * @template T - Tipo dos dados retornados
- * @param api - Instância do Axios configurada
- * @param url - Endpoint da API (sem barra inicial)
- * @param search - Parâmetros opcionais de busca/paginação
- * @param signal - Signal para cancelamento da requisição
- * @returns Promise com dados encontrados ou array de erros
+ * @template T - Type of individual items in the response
+ * @param {AxiosInstance} api - Configured Axios instance with authentication
+ * @param {string} url - API endpoint path (without leading slash, e.g., 'users')
+ * @param {Search} [search] - Optional search, pagination and sorting parameters
+ * @param {number} [search.page] - Page number (zero-indexed)
+ * @param {number} [search.size] - Number of items per page
+ * @param {string} [search.value] - Search term for filtering
+ * @param {Object} [search.sort] - Sorting configuration
+ * @param {string} [search.sort.key] - Field name to sort by
+ * @param {'asc'|'desc'} [search.sort.order] - Sort order
+ * @param {AbortSignal} [signal] - Signal for request cancellation
+ * @returns {Promise<T[] | Page<T> | ErrorMessage[]>} Promise resolving to:
+ *   - Array of items (unpaginated)
+ *   - Page object (paginated)
+ *   - Array of errors (on failure)
+ *
+ * @throws {never} Never throws - all errors are caught and returned as ErrorMessage[]
  *
  * @example
  * ```typescript
- * // Busca simples
- * const all = await retrieve(api, 'users')
+ * // Simple search
+ * const allUsers = await retrieve(api, 'users')
  *
- * // Busca paginada
+ * // Paginated search
  * const page = await retrieve(api, 'users', { page: 0, size: 10 })
  *
- * // Busca com filtro e ordenação
+ * // Search with filter + pagination + sorting
  * const filtered = await retrieve(api, 'users', {
- *   value: 'João',
+ *   value: 'John',
  *   page: 0,
  *   size: 10,
  *   sort: { key: 'name', order: 'ASC' }
  * })
+ *
+ * // With cancellation support
+ * const controller = new AbortController()
+ * const promise = retrieve(api, 'posts', { page: 0, size: 15 }, controller.signal)
  * ```
  */
-export declare const retrieve: <T>(api: AxiosInstance, url: string, search?: Search, signal?: AbortSignal) => Promise<ErrorMessage[] | T>;
+export declare const retrieve: <T>(api: AxiosInstance, url: string, search?: Search, signal?: AbortSignal) => Promise<Page<T> | ErrorMessage[]>;
 /**
- * Atualiza um registro existente na API
+ * Updates an existing record in the API via PUT request
  *
- * @template T - Tipo do objeto a ser atualizado
- * @param api - Instância do Axios configurada
- * @param url - Endpoint da API (sem barra inicial)
- * @param object - Dados atualizados do objeto
- * @returns Promise com dados atualizados ou array de erros
+ * @template T - Type of object to be updated
+ * @param {AxiosInstance} api - Configured Axios instance with authentication
+ * @param {string} url - API endpoint path (without leading slash, e.g., 'users')
+ * @param {T} object - Updated object data (must include identifier)
+ * @returns {Promise<T | ErrorMessage[]>} Promise resolving to response or array of errors
+ *
+ * @throws {never} Never throws - all errors are caught and returned as ErrorMessage[]
  *
  * @example
  * ```typescript
- * const result = await update(api, 'users', { id: 1, name: 'João Silva' })
+ * const result = await update(api, 'users', { id: 1, name: 'John Silva' })
  * ```
  */
-export declare const update: <T>(api: AxiosInstance, url: string, object: T) => Promise<ErrorMessage[] | T>;
+export declare const update: <T>(api: AxiosInstance, url: string, object: T) => Promise<T | ErrorMessage[]>;
 /**
- * Remove um registro específico da API
+ * Removes a specific record from the API via DELETE request
+ *
+ * @template T - Type of response
+ * @param {AxiosInstance} api - Configured Axios instance with authentication
+ * @param {string} url - API endpoint path (without leading slash, e.g., 'users')
+ * @param {string} id - ID of the record to be removed
+ * @returns {Promise<T | ErrorMessage[]>} Promise resolving to response or array of errors
  *
- * @template T - Tipo da resposta
- * @param api - Instância do Axios configurada
- * @param url - Endpoint da API (sem barra inicial)
- * @param id - ID do registro a ser removido
- * @returns Promise com resposta ou array de erros
+ * @throws {never} Never throws - all errors are caught and returned as ErrorMessage[]
  *
  * @example
  * ```typescript
@@ -90,26 +130,39 @@ export declare const update: <T>(api: AxiosInstance, url: string, object: T) =>
  */
 export declare const remove: <T>(api: AxiosInstance, url: string, id: string) => Promise<ErrorMessage[] | T>;
 /**
- * Remove registros com chave composta (múltiplos IDs)
- *
- * @template T - Tipo da resposta
- * @param api - Instância do Axios configurada
- * @param url - Endpoint da API (sem barra inicial)
- * @param object - Objeto com dados para remoção
- * @param one - Primeiro identificador
- * @param two - Segundo identificador
- * @param three - Terceiro identificador (opcional)
- * @param four - Quarto identificador (opcional)
- * @returns Promise com resposta ou array de erros
+ * Removes a record with composite key (multiple identifiers) via DELETE request
+ *
+ * @template T - Type of response
+ * @param {AxiosInstance} api - Configured Axios instance with authentication
+ * @param {string} url - API endpoint path (without leading slash)
+ * @param {Object} object - Object with additional data for deletion (if needed by backend)
+ * @param {string} one - First identifier segment
+ * @param {string} two - Second identifier segment
+ * @param {string} three - Third identifier segment (optional, pass '' if unused)
+ * @param {string} four - Fourth identifier segment (optional, pass '' if unused)
+ * @returns {Promise<T | ErrorMessage[]>} Promise resolving to response or array of errors
+ *
+ * @throws {never} Never throws - all errors are caught and returned as ErrorMessage[]
+ *
+ * @example
+ * ```typescript
+ * // Delete with 2-part composite key
+ * const result = await removeComposite(api, 'user-roles', {}, 'user-123', 'role-admin', '', '')
+  * ```
  */
 export declare const removeComposite: <T>(api: AxiosInstance, url: string, object: Object, one: string, two: string, three: string, four: string) => Promise<ErrorMessage[] | T>;
 /**
- * Remove todos os registros de um endpoint específico
+ * Removes all records from a specific endpoint via DELETE request
+ *
+ * ⚠️ **WARNING**: This is a destructive operation that removes ALL records.
+ * Use with extreme caution and ensure this is the intended action.
+ *
+ * @template T - Type of response
+ * @param {AxiosInstance} api - Configured Axios instance with authentication
+ * @param {string} url - API endpoint path (without leading slash)
+ * @returns {Promise<T | ErrorMessage[]>} Promise resolving to response or array of errors
  *
- * @template T - Tipo da resposta
- * @param api - Instância do Axios configurada
- * @param url - Endpoint da API (sem barra inicial)
- * @returns Promise com resposta ou array de erros
+ * @throws {never} Never throws - all errors are caught and returned as ErrorMessage[]
  *
  * @example
  * ```typescript

package/dist/services/crud.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crud.d.ts","sourceRoot":"","sources":["../../src/services/crud.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AA2BzC;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,MAAM,GAAU,CAAC,EAAG,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,QAAQ,CAAC,iBAI1E,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,GAAU,CAAC,EAAG,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,QAAQ,CAAC,EAAE,gCAI/E,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,QAAQ,GAAU,CAAC,EAAG,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,SAAS,MAAM,EAAE,SAAS,WAAW,gCAcxG,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,MAAM,GAAU,CAAC,EAAG,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,QAAQ,CAAC,gCAI1E,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,MAAM,GAAU,CAAC,EAAG,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,IAAI,MAAM,gCAI3E,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,GAAU,CAAC,EAAG,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,QAAQ,MAAM,EAAE,KAAK,MAAM,EAAE,KAAK,MAAM,EAAE,OAAO,MAAM,EAAE,MAAM,MAAM,gCAU/I,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,SAAS,GAAU,CAAC,EAAG,KAAK,aAAa,EAAE,KAAK,MAAM,gCAIlE,CAAA"}
+{"version":3,"file":"crud.d.ts","sourceRoot":"","sources":["../../src/services/crud.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAEzC,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAA;AA+BxC;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,MAAM,GAAU,CAAC,EAAG,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,QAAQ,CAAC,KAAG,OAAO,CAAC,CAAC,GAAG,YAAY,EAAE,CAIvG,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,SAAS,GAAU,CAAC,EAAG,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,QAAQ,CAAC,EAAE,KAAG,OAAO,CAAC,CAAC,GAAG,YAAY,EAAE,CAI5G,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,eAAO,MAAM,QAAQ,GAAU,CAAC,EAAE,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,SAAS,MAAM,EAAE,SAAS,WAAW,KAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,YAAY,EAAE,CAM1I,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,MAAM,GAAU,CAAC,EAAG,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,QAAQ,CAAC,KAAG,OAAO,CAAC,CAAC,GAAG,YAAY,EAAE,CAIvG,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,MAAM,GAAU,CAAC,EAAG,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,IAAI,MAAM,gCAI3E,CAAA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,eAAe,GAAU,CAAC,EAAG,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,QAAQ,MAAM,EAAE,KAAK,MAAM,EAAE,KAAK,MAAM,EAAE,OAAO,MAAM,EAAE,MAAM,MAAM,gCAU/I,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,SAAS,GAAU,CAAC,EAAG,KAAK,aAAa,EAAE,KAAK,MAAM,gCAIlE,CAAA"}

package/dist/services/crud.js

@@ -1,20 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.removeAll = exports.removeComposite = exports.remove = exports.update = exports.retrieve = exports.createAll = exports.create = void 0;
-// Códigos de status HTTP:
-// Respostas de informação (100-199),
-// Respostas de sucesso (200-299),
-// Redirecionamentos (300-399)
-// Erros do cliente (400-499)
-// Erros do servidor (500-599).
+const api_1 = require("./api");
 /**
- * Processa erros de resposta da API e converte em formato padronizado
+ * HTTP Status Code Reference:
+ * - 1xx: Informational responses
+ * - 2xx: Success responses
+ * - 3xx: Redirects
+ * - 4xx: Client errors
+ * - 5xx: Server errors
+ */
+/**
+ * Processes API response errors and converts to standardized format
  *
- * @param error - Objeto de erro do Axios
- * @returns Array de mensagens de erro formatadas
+ * @param {any} error - Axios error object from catch block
+ * @returns {ErrorMessage[]} Array of formatted error messages with field and message properties
+ *
+ * @internal This is a utility function used internally by CRUD operations
  */
 const addError = (error) => {
-    var _a, _b;
+    var _a, _b, _c, _d;
     let errorMessage = [];
     if (error.response.data.validationErrors !== undefined) {
         (_b = (_a = error.response.data) === null || _a === void 0 ? void 0 : _a.validationErrors) === null || _b === void 0 ? void 0 : _b.forEach((element) => {
@@ -22,22 +27,25 @@ const addError = (error) => {
         });
     }
     else {
-        errorMessage.push({ field: 'Error', message: 'Internal Error' });
+        errorMessage.push({ field: 'Error', message: ((_d = (_c = error.response) === null || _c === void 0 ? void 0 : _c.data) === null || _d === void 0 ? void 0 : _d.message) || 'Internal Server Error' });
     }
     return errorMessage;
 };
 /**
- * Cria um novo registro na API
+ * Creates a new record in the API via POST request
+ *
+ * @template T - Type of object to be created
+ * @param {AxiosInstance} api - Configured Axios instance with authentication
+ * @param {string} url - API endpoint path (without leading slash, e.g., 'users')
+ * @param {T} object - Object data to be created
+ * @returns {Promise<T | ErrorMessage[]>} Promise resolving to created data or array of errors
  *
- * @template T - Tipo do objeto a ser criado
- * @param api - Instância do Axios configurada
- * @param url - Endpoint da API (sem barra inicial)
- * @param object - Dados do objeto a ser criado
- * @returns Promise com dados criados ou array de erros
+ * @throws {never} Never throws - all errors are caught and returned as ErrorMessage[]
  *
  * @example
  * ```typescript
- * const result = await create(api, 'users', { name: 'João', email: 'joao@exemplo.com' })
+ * // Create a user
+ * const result = await create(api, 'users', { name: 'John Snow', email: 'john@example.com', role: 'USER' })
  * ```
  */
 const create = async (api, url, object) => {
@@ -47,13 +55,27 @@ const create = async (api, url, object) => {
 };
 exports.create = create;
 /**
- * Cria múltiplos registros de uma vez na API
+ * Creates multiple records at once in the API via batch POST request
  *
- * @template T - Tipo dos objetos a serem criados
- * @param api - Instância do Axios configurada
- * @param url - Endpoint da API (sem barra inicial)
- * @param object - Array de objetos a serem criados
- * @returns Promise com dados criados ou array de erros
+ * @template T - Type of objects to be created
+ * @param {AxiosInstance} api - Configured Axios instance with authentication
+ * @param {string} url - API endpoint path (without leading slash, e.g., 'users')
+ * @param {T[]} object - Array of objects to be created
+ * @returns {Promise<T | ErrorMessage[]>} Promise resolving to created data or array of errors
+ *
+ * @throws {never} Never throws - all errors are caught and returned as ErrorMessage[]
+ *
+ * @example
+ * ```typescript
+ * // Create multiple users at once
+ * const users = [
+ *   { name: 'John Snow', email: 'john@example.com' },
+ *   { name: 'Jane Smith', email: 'jane@example.com' },
+ *   { name: 'Bob Johnson', email: 'bob@example.com' }
+ * ]
+ *
+ * const result = await createAll(api, 'users', users)
+ * ```
  */
 const createAll = async (api, url, object) => {
     return await api.post(`/${url}/createAll`, object)
@@ -62,68 +84,78 @@ const createAll = async (api, url, object) => {
 };
 exports.createAll = createAll;
 /**
- * Busca/recupera registros da API com suporte a paginação e busca
- *
- * Comportamentos:
- * - Sem search: busca todos os registros
- * - Com page/size: busca paginada
- * - Com sort: busca paginada e ordenada
- *
- * @template T - Tipo dos dados retornados
- * @param api - Instância do Axios configurada
- * @param url - Endpoint da API (sem barra inicial)
- * @param search - Parâmetros opcionais de busca/paginação
- * @param signal - Signal para cancelamento da requisição
- * @returns Promise com dados encontrados ou array de erros
+ * Retrieves records from the API with optional pagination, search, and sorting support
+ *
+ * This function delegates to `fetchPage` for paginated requests and handles
+ * unpaginated retrieval directly.
+ *
+ * Behaviors based on parameters:
+ * - Without search: retrieves all records
+ * - With page/size: paginated search
+ * - With sort: paginated and sorted search
+ *
+ * @template T - Type of individual items in the response
+ * @param {AxiosInstance} api - Configured Axios instance with authentication
+ * @param {string} url - API endpoint path (without leading slash, e.g., 'users')
+ * @param {Search} [search] - Optional search, pagination and sorting parameters
+ * @param {number} [search.page] - Page number (zero-indexed)
+ * @param {number} [search.size] - Number of items per page
+ * @param {string} [search.value] - Search term for filtering
+ * @param {Object} [search.sort] - Sorting configuration
+ * @param {string} [search.sort.key] - Field name to sort by
+ * @param {'asc'|'desc'} [search.sort.order] - Sort order
+ * @param {AbortSignal} [signal] - Signal for request cancellation
+ * @returns {Promise<T[] | Page<T> | ErrorMessage[]>} Promise resolving to:
+ *   - Array of items (unpaginated)
+ *   - Page object (paginated)
+ *   - Array of errors (on failure)
+ *
+ * @throws {never} Never throws - all errors are caught and returned as ErrorMessage[]
  *
  * @example
  * ```typescript
- * // Busca simples
- * const all = await retrieve(api, 'users')
+ * // Simple search
+ * const allUsers = await retrieve(api, 'users')
  *
- * // Busca paginada
+ * // Paginated search
  * const page = await retrieve(api, 'users', { page: 0, size: 10 })
  *
- * // Busca com filtro e ordenação
+ * // Search with filter + pagination + sorting
  * const filtered = await retrieve(api, 'users', {
- *   value: 'João',
+ *   value: 'John',
  *   page: 0,
  *   size: 10,
  *   sort: { key: 'name', order: 'ASC' }
  * })
+ *
+ * // With cancellation support
+ * const controller = new AbortController()
+ * const promise = retrieve(api, 'posts', { page: 0, size: 15 }, controller.signal)
  * ```
  */
 const retrieve = async (api, url, search, signal) => {
-    var _a, _b, _c;
-    if ((search === null || search === void 0 ? void 0 : search.page) === undefined && (search === null || search === void 0 ? void 0 : search.size) === undefined) {
-        return await api.get(`/${url}`)
-            .then(response => { return response.data; })
-            .catch(error => { return addError(error); });
+    try {
+        return await (0, api_1.fetchPage)(api, url, search, signal);
     }
-    else if (((_a = search === null || search === void 0 ? void 0 : search.sort) === null || _a === void 0 ? void 0 : _a.order) === undefined) {
-        return await api.get(`/${url}?value=${search === null || search === void 0 ? void 0 : search.value}`, { params: { page: search === null || search === void 0 ? void 0 : search.page, size: search === null || search === void 0 ? void 0 : search.size }, signal })
-            .then(response => { return response.data; })
-            .catch(error => { return addError(error); });
-    }
-    else {
-        return await api.get(`/${url}?value=${search === null || search === void 0 ? void 0 : search.value}`, { params: { page: search === null || search === void 0 ? void 0 : search.page, size: search === null || search === void 0 ? void 0 : search.size, sort: `${(_b = search === null || search === void 0 ? void 0 : search.sort) === null || _b === void 0 ? void 0 : _b.key},${(_c = search === null || search === void 0 ? void 0 : search.sort) === null || _c === void 0 ? void 0 : _c.order}` }, signal })
-            .then(response => { return response.data; })
-            .catch(error => { return addError(error); });
+    catch (error) {
+        return addError(error);
     }
 };
 exports.retrieve = retrieve;
 /**
- * Atualiza um registro existente na API
+ * Updates an existing record in the API via PUT request
+ *
+ * @template T - Type of object to be updated
+ * @param {AxiosInstance} api - Configured Axios instance with authentication
+ * @param {string} url - API endpoint path (without leading slash, e.g., 'users')
+ * @param {T} object - Updated object data (must include identifier)
+ * @returns {Promise<T | ErrorMessage[]>} Promise resolving to response or array of errors
  *
- * @template T - Tipo do objeto a ser atualizado
- * @param api - Instância do Axios configurada
- * @param url - Endpoint da API (sem barra inicial)
- * @param object - Dados atualizados do objeto
- * @returns Promise com dados atualizados ou array de erros
+ * @throws {never} Never throws - all errors are caught and returned as ErrorMessage[]
  *
  * @example
  * ```typescript
- * const result = await update(api, 'users', { id: 1, name: 'João Silva' })
+ * const result = await update(api, 'users', { id: 1, name: 'John Silva' })
  * ```
  */
 const update = async (api, url, object) => {
@@ -133,13 +165,15 @@ const update = async (api, url, object) => {
 };
 exports.update = update;
 /**
- * Remove um registro específico da API
+ * Removes a specific record from the API via DELETE request
+ *
+ * @template T - Type of response
+ * @param {AxiosInstance} api - Configured Axios instance with authentication
+ * @param {string} url - API endpoint path (without leading slash, e.g., 'users')
+ * @param {string} id - ID of the record to be removed
+ * @returns {Promise<T | ErrorMessage[]>} Promise resolving to response or array of errors
  *
- * @template T - Tipo da resposta
- * @param api - Instância do Axios configurada
- * @param url - Endpoint da API (sem barra inicial)
- * @param id - ID do registro a ser removido
- * @returns Promise com resposta ou array de erros
+ * @throws {never} Never throws - all errors are caught and returned as ErrorMessage[]
  *
  * @example
  * ```typescript
@@ -153,17 +187,25 @@ const remove = async (api, url, id) => {
 };
 exports.remove = remove;
 /**
- * Remove registros com chave composta (múltiplos IDs)
- *
- * @template T - Tipo da resposta
- * @param api - Instância do Axios configurada
- * @param url - Endpoint da API (sem barra inicial)
- * @param object - Objeto com dados para remoção
- * @param one - Primeiro identificador
- * @param two - Segundo identificador
- * @param three - Terceiro identificador (opcional)
- * @param four - Quarto identificador (opcional)
- * @returns Promise com resposta ou array de erros
+ * Removes a record with composite key (multiple identifiers) via DELETE request
+ *
+ * @template T - Type of response
+ * @param {AxiosInstance} api - Configured Axios instance with authentication
+ * @param {string} url - API endpoint path (without leading slash)
+ * @param {Object} object - Object with additional data for deletion (if needed by backend)
+ * @param {string} one - First identifier segment
+ * @param {string} two - Second identifier segment
+ * @param {string} three - Third identifier segment (optional, pass '' if unused)
+ * @param {string} four - Fourth identifier segment (optional, pass '' if unused)
+ * @returns {Promise<T | ErrorMessage[]>} Promise resolving to response or array of errors
+ *
+ * @throws {never} Never throws - all errors are caught and returned as ErrorMessage[]
+ *
+ * @example
+ * ```typescript
+ * // Delete with 2-part composite key
+ * const result = await removeComposite(api, 'user-roles', {}, 'user-123', 'role-admin', '', '')
+  * ```
  */
 const removeComposite = async (api, url, object, one, two, three, four) => {
     if (three !== '' && four !== '') {
@@ -179,12 +221,17 @@ const removeComposite = async (api, url, object, one, two, three, four) => {
 };
 exports.removeComposite = removeComposite;
 /**
- * Remove todos os registros de um endpoint específico
+ * Removes all records from a specific endpoint via DELETE request
+ *
+ * ⚠️ **WARNING**: This is a destructive operation that removes ALL records.
+ * Use with extreme caution and ensure this is the intended action.
+ *
+ * @template T - Type of response
+ * @param {AxiosInstance} api - Configured Axios instance with authentication
+ * @param {string} url - API endpoint path (without leading slash)
+ * @returns {Promise<T | ErrorMessage[]>} Promise resolving to response or array of errors
  *
- * @template T - Tipo da resposta
- * @param api - Instância do Axios configurada
- * @param url - Endpoint da API (sem barra inicial)
- * @returns Promise com resposta ou array de erros
+ * @throws {never} Never throws - all errors are caught and returned as ErrorMessage[]
  *
  * @example
  * ```typescript