@gzl10/baserow 1.2.0

package/src/utils/validation.ts

@@ -0,0 +1,463 @@
+/**
+ * Utilidades de validación para la librería @gzl10/baserow
+ *
+ * Proporciona funciones de validación reutilizables para parámetros,
+ * configuraciones y datos de entrada. Todas las funciones lanzan
+ * BaserowValidationError con mensajes estructurados para facilitar
+ * el debugging y manejo de errores.
+ *
+ * **Funciones disponibles:**
+ * - Validación de campos requeridos y tipos básicos
+ * - Validación de URLs y tokens
+ * - Sanitización de nombres de campos
+ * - Validación de tipos de campos de Baserow
+ * - Utilidades para procesamiento bulk (chunking)
+ *
+ * @since 1.0.0
+ */
+
+import { BaserowValidationError } from '../types'
+
+/**
+ * Valida que un valor no sea null, undefined o string vacío
+ *
+ * Función genérica que garantiza que un valor requerido esté presente.
+ * Utilizada en toda la librería para validar parámetros obligatorios.
+ *
+ * @template T - Tipo del valor a validar
+ * @param value - Valor a validar
+ * @param fieldName - Nombre del campo para mensajes de error
+ * @returns El valor validado (mismo tipo)
+ *
+ * @throws {BaserowValidationError} Si el valor es null, undefined o string vacío
+ *
+ * @example
+ * ```typescript
+ * // Validar parámetros requeridos
+ * const name = validateRequired(userInput.name, 'name')
+ * const id = validateRequired(params.id, 'table ID')
+ *
+ * // Usada internamente en servicios
+ * validateRequired(tableId, 'table ID') // Lanza error si tableId es null/undefined
+ * ```
+ *
+ * @since 1.0.0
+ */
+export function validateRequired<T>(value: T, fieldName: string): T {
+  if (value === undefined || value === null || value === '') {
+    throw new BaserowValidationError(`${fieldName} is required`, {
+      [fieldName]: [`${fieldName} is required`]
+    })
+  }
+  return value
+}
+
+/**
+ * Valida que un número sea positivo (mayor que 0)
+ *
+ * Utilizada para validar IDs, cantidades, tamaños de página y otros
+ * valores numéricos que deben ser positivos en la API de Baserow.
+ *
+ * @param value - Número a validar
+ * @param fieldName - Nombre del campo para mensajes de error
+ * @returns El número validado
+ *
+ * @throws {BaserowValidationError} Si no es un número o es menor/igual que 0
+ *
+ * @example
+ * ```typescript
+ * // Validar IDs
+ * const tableId = validatePositiveNumber(params.tableId, 'table ID')
+ * const fieldId = validatePositiveNumber(data.fieldId, 'field ID')
+ *
+ * // Validar opciones de paginación
+ * const pageSize = validatePositiveNumber(options.size, 'page size')
+ * ```
+ *
+ * @since 1.0.0
+ */
+export function validatePositiveNumber(value: number, fieldName: string): number {
+  if (typeof value !== 'number' || value <= 0) {
+    throw new BaserowValidationError(`${fieldName} must be a positive number`, {
+      [fieldName]: [`${fieldName} must be a positive number`]
+    })
+  }
+  return value
+}
+
+/**
+ * Valida que un valor sea un string con longitud mínima
+ *
+ * Verifica tipo string y longitud mínima configurable.
+ * Utilizada para validar nombres, descripciones y otros campos de texto.
+ *
+ * @param value - Valor a validar
+ * @param fieldName - Nombre del campo para mensajes de error
+ * @param minLength - Longitud mínima requerida (default: 1)
+ * @returns El string validado
+ *
+ * @throws {BaserowValidationError} Si no es string o no cumple longitud mínima
+ *
+ * @example
+ * ```typescript
+ * // Validar nombres de recursos
+ * const tableName = validateString(data.name, 'table name')
+ * const fieldName = validateString(field.name, 'field name')
+ *
+ * // Validar con longitud mínima específica
+ * const description = validateString(data.desc, 'description', 10)
+ * ```
+ *
+ * @since 1.0.0
+ */
+export function validateString(value: any, fieldName: string, minLength = 1): string {
+  if (typeof value !== 'string' || value.length < minLength) {
+    throw new BaserowValidationError(`${fieldName} must be a string with at least ${minLength} character(s)`, {
+      [fieldName]: [`${fieldName} must be a string with at least ${minLength} character(s)`]
+    })
+  }
+  return value
+}
+
+/**
+ * Valida que un string sea una URL válida
+ *
+ * Utiliza el constructor URL nativo de JavaScript para validar formato.
+ * Soporta todos los protocolos válidos (http, https, ftp, etc.).
+ *
+ * @param url - String URL a validar
+ * @param fieldName - Nombre del campo para mensajes de error (default: 'url')
+ * @returns La URL validada
+ *
+ * @throws {BaserowValidationError} Si el formato de URL es inválido
+ *
+ * @example
+ * ```typescript
+ * // Validar URLs de configuración
+ * const baseUrl = validateUrl(config.url, 'Baserow URL')
+ * const webhookUrl = validateUrl(data.webhook_url, 'webhook URL')
+ *
+ * // Validar campos URL de Baserow
+ * const siteUrl = validateUrl(fieldData.url, 'website URL')
+ * ```
+ *
+ * @since 1.0.0
+ */
+export function validateUrl(url: string, fieldName: string = 'url'): string {
+  try {
+    new URL(url)
+    return url
+  } catch {
+    throw new BaserowValidationError(`${fieldName} must be a valid URL`, {
+      [fieldName]: [`${fieldName} must be a valid URL`]
+    })
+  }
+}
+
+/**
+ * Verifica si un string es una URL válida sin lanzar errores
+ *
+ * Versión no-throw de validateUrl() que retorna boolean.
+ * Útil para validaciones condicionales y filtros.
+ *
+ * @param url - String URL a verificar
+ * @returns true si es URL válida, false si no
+ *
+ * @example
+ * ```typescript
+ * // Verificación condicional
+ * if (isValidUrl(userInput)) {
+ *   // Procesar como URL
+ * } else {
+ *   // Manejar como texto plano
+ * }
+ *
+ * // Filtrar URLs válidas
+ * const validUrls = urls.filter(isValidUrl)
+ * ```
+ *
+ * @since 1.0.0
+ */
+export function isValidUrl(url: string): boolean {
+  try {
+    new URL(url)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Valida un token de autenticación (Database Token o JWT)
+ *
+ * Verifica que el token no esté vacío y remueve espacios extra.
+ * Soporta tanto Database Tokens como JWT tokens de Baserow.
+ *
+ * @param token - Token a validar
+ * @returns El token validado y sanitizado (sin espacios)
+ *
+ * @throws {BaserowValidationError} Si el token está vacío o no es string
+ *
+ * @example
+ * ```typescript
+ * // Validar tokens de configuración
+ * const dbToken = validateToken(config.token)
+ * const jwtToken = validateToken(process.env.BASEROW_JWT)
+ *
+ * // Se auto-sanitiza
+ * const clean = validateToken('  token123  ') // returns 'token123'
+ * ```
+ *
+ * @since 1.0.0
+ */
+export function validateToken(token: string): string {
+  if (!token || typeof token !== 'string' || token.trim().length === 0) {
+    throw new BaserowValidationError('Token is required and cannot be empty', {
+      token: ['Token is required and cannot be empty']
+    })
+  }
+  return token.trim()
+}
+
+/**
+ * Valida la configuración completa de un cliente Baserow
+ *
+ * Valida que la configuración tenga estructura correcta con URL y token válidos.
+ * Utilizada por todos los clientes (BaserowClient, BaserowAdmin*) durante la inicialización.
+ *
+ * @param config - Configuración a validar
+ * @returns void (lanza error si es inválida)
+ *
+ * @throws {BaserowValidationError} Si faltan campos requeridos o son inválidos
+ *
+ * @example
+ * ```typescript
+ * // Validación en constructores de clientes
+ * validateConfig({
+ *   url: 'https://baserow.example.com',
+ *   token: 'valid-token-123'
+ * }) // OK
+ *
+ * validateConfig({
+ *   url: 'invalid-url',
+ *   token: ''
+ * }) // Lanza BaserowValidationError
+ * ```
+ *
+ * @since 1.0.0
+ */
+export function validateConfig(config: any): void {
+  if (!config || typeof config !== 'object') {
+    throw new BaserowValidationError('Config must be an object', {
+      config: ['Config must be an object']
+    })
+  }
+
+  validateRequired(config.url, 'url')
+  validateRequired(config.token, 'token')
+
+  if (!isValidUrl(config.url)) {
+    throw new BaserowValidationError('URL must be a valid URL', {
+      url: ['URL must be a valid URL']
+    })
+  }
+
+  validateToken(config.token)
+}
+
+/**
+ * Sanitiza y valida nombres de campos de Baserow
+ *
+ * Aplica las reglas de nombres de campos de Baserow:
+ * - Debe ser string no vacío
+ * - Máximo 255 caracteres
+ * - Remueve espacios al inicio y final
+ *
+ * @param name - Nombre de campo a sanitizar
+ * @returns El nombre sanitizado y validado
+ *
+ * @throws {BaserowValidationError} Si el nombre es inválido
+ *
+ * @example
+ * ```typescript
+ * // Sanitizar nombres de entrada del usuario
+ * const fieldName = sanitizeFieldName('  Nombre del Campo  ') // 'Nombre del Campo'
+ * const cleanName = sanitizeFieldName(userInput.fieldName)
+ *
+ * // Validar antes de crear campos
+ * const safeName = sanitizeFieldName(data.name)
+ * await fieldService.createTextField(tableId, safeName)
+ * ```
+ *
+ * @since 1.0.0
+ */
+export function sanitizeFieldName(name: string): string {
+  if (typeof name !== 'string' || name == null) {
+    throw new BaserowValidationError('Field name must be a string', {
+      name: ['Field name must be a string']
+    })
+  }
+
+  // Eliminar espacios al inicio y final
+  name = name.trim()
+
+  if (name.length === 0) {
+    throw new BaserowValidationError('Field name cannot be empty', {
+      name: ['Field name cannot be empty']
+    })
+  }
+
+  if (name.length > 255) {
+    throw new BaserowValidationError('Field name cannot exceed 255 characters', {
+      name: ['Field name cannot exceed 255 characters']
+    })
+  }
+
+  return name
+}
+
+/**
+ * Divide un array en chunks (trozos) de tamaño específico
+ *
+ * Utilizada para operaciones bulk optimizadas que procesan datos en lotes
+ * para evitar timeouts y limitar el uso de memoria. Esencial para
+ * createBulk(), updateBulk() y deleteBulk().
+ *
+ * @template T - Tipo de elementos del array
+ * @param array - Array a dividir en chunks
+ * @param chunkSize - Tamaño de cada chunk (debe ser positivo)
+ * @returns Array de arrays (chunks) con el tamaño especificado
+ *
+ * @throws {BaserowValidationError} Si chunkSize es menor o igual que 0
+ *
+ * @example
+ * ```typescript
+ * // Procesar rows en lotes de 50
+ * const rows = [...] // 1000 rows
+ * const chunks = chunkArray(rows, 50) // [[50 rows], [50 rows], ...]
+ *
+ * for (const chunk of chunks) {
+ *   await rowService.createBulk(tableId, chunk)
+ * }
+ *
+ * // Procesar IDs para delete bulk
+ * const ids = [1, 2, 3, ..., 100]
+ * const idChunks = chunkArray(ids, 25) // [[25 IDs], [25 IDs], ...]
+ * ```
+ *
+ * @since 1.0.0
+ */
+export function chunkArray<T>(array: T[], chunkSize: number): T[][] {
+  if (chunkSize <= 0) {
+    throw new BaserowValidationError('Chunk size must be positive', {
+      chunkSize: ['Chunk size must be positive']
+    })
+  }
+
+  const chunks: T[][] = []
+  for (let i = 0; i < array.length; i += chunkSize) {
+    chunks.push(array.slice(i, i + chunkSize))
+  }
+  return chunks
+}
+
+/**
+ * Crea una pausa (delay) asíncrona por un tiempo especificado
+ *
+ * Utilizada para retry logic, rate limiting manual y esperas
+ * entre operaciones. Especialmente útil en tests y operaciones
+ * que requieren delays entre requests.
+ *
+ * @param ms - Millisegundos a esperar
+ * @returns Promise que se resuelve después del delay
+ *
+ * @example
+ * ```typescript
+ * // Esperar entre operaciones
+ * await createRow(data1)
+ * await delay(1000) // Esperar 1 segundo
+ * await createRow(data2)
+ *
+ * // Retry logic con delay
+ * for (let i = 0; i < 3; i++) {
+ *   try {
+ *     return await operation()
+ *   } catch (error) {
+ *     if (i < 2) await delay(1000 * (i + 1)) // Backoff: 1s, 2s
+ *   }
+ * }
+ * ```
+ *
+ * @since 1.0.0
+ */
+export function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+const VALID_FIELD_TYPES = [
+  'text',
+  'long_text',
+  'url',
+  'email',
+  'phone_number',
+  'number',
+  'rating',
+  'boolean',
+  'date',
+  'last_modified',
+  'last_modified_by',
+  'created_on',
+  'created_by',
+  'single_select',
+  'multiple_select',
+  'file',
+  'multiple_collaborators',
+  'link_row',
+  'count',
+  'rollup',
+  'lookup',
+  'formula',
+  'autonumber'
+] as const
+
+/**
+ * Valida que un tipo de campo sea soportado por Baserow
+ *
+ * Verifica que el tipo esté en la lista de 21 tipos soportados por la librería.
+ * Lista actualizada con los nuevos tipos avanzados (file, autonumber, count, rollup, lookup).
+ *
+ * **Tipos soportados (21/22):**
+ * - **Texto**: text, long_text, url, email, phone_number
+ * - **Numéricos**: number, rating, boolean
+ * - **Fecha/Auditoría**: date, last_modified, last_modified_by, created_on, created_by
+ * - **Selección**: single_select, multiple_select
+ * - **Relacionales**: link_row, formula
+ * - **Avanzados**: file, autonumber, count, rollup, lookup
+ * - **Otros**: multiple_collaborators
+ *
+ * @param type - Tipo de campo a validar
+ * @param fieldName - Nombre del campo para mensajes de error (default: 'type')
+ * @returns El tipo validado
+ *
+ * @throws {BaserowValidationError} Si el tipo no está soportado
+ *
+ * @example
+ * ```typescript
+ * // Validar antes de crear campos
+ * const fieldType = validateFieldType('text', 'field type')
+ * const advancedType = validateFieldType('rollup', 'rollup field type')
+ *
+ * // Usar en FieldService
+ * validateFieldType(data.type) // Lanza error si no es soportado
+ * ```
+ *
+ * @since 1.0.0
+ */
+export function validateFieldType(type: string, fieldName: string = 'type'): string {
+  if (!VALID_FIELD_TYPES.includes(type as any)) {
+    throw new BaserowValidationError(`Invalid field type: ${type}`, {
+      [fieldName]: [`Field type must be one of: ${VALID_FIELD_TYPES.join(', ')}`]
+    })
+  }
+  return type
+}