@gzl10/baserow 1.2.0

package/src/utils/prisma-mapper.ts

@@ -0,0 +1,961 @@
+import {
+  QueryOptions,
+  PrismaLikeQueryOptions,
+  WhereClause,
+  OrderByClause,
+  SelectClause,
+  FieldOperators
+} from '../types/requests'
+import { FieldMetadata } from './field-cache'
+
+/**
+ * Mapper para transformar entre sintaxis Prisma y Baserow API
+ *
+ * Esta clase proporciona métodos estáticos para convertir opciones de consulta
+ * estilo Prisma a formato compatible con la API de Baserow, permitiendo
+ * una experiencia de desarrollador familiar mientras manteniendo compatibilidad
+ * con las capacidades específicas de Baserow.
+ *
+ * **Transformaciones principales:**
+ * - `where` → `filters` con operadores Baserow
+ * - `orderBy` → `order_by` string
+ * - `select` → `include`/`exclude` arrays
+ * - `take`/`skip` → `size`/`page`
+ * - Validación y optimización de consultas
+ *
+ * @aiPattern
+ * ## 🎯 5 Patrones de Uso Comunes
+ *
+ * **1. Búsqueda Simple con Paginación**
+ * ```typescript
+ * // Prisma-like query para buscar usuarios activos
+ * const query = {
+ *   where: { status: 'active' },
+ *   orderBy: { created_at: 'desc' },
+ *   take: 20,
+ *   skip: 0
+ * }
+ *
+ * const baserowQuery = PrismaBaserowMapper.transformPrismaToBaserow(query)
+ * const rows = await client.rows.list(tableId, baserowQuery)
+ * ```
+ *
+ * **2. Filtros Complejos con AND**
+ * ```typescript
+ * // Combinar múltiples condiciones (todas deben cumplirse)
+ * const query = {
+ *   where: {
+ *     AND: [
+ *       { age: { gte: 18, lt: 65 } },
+ *       { email: { contains: '@company.com' } },
+ *       { status: 'active' }
+ *     ]
+ *   }
+ * }
+ *
+ * const baserowQuery = PrismaBaserowMapper.transformPrismaToBaserow(query)
+ * // Transforma a: filter__age__higher_than_or_equal=18&filter__age__lower_than=65&...
+ * ```
+ *
+ * **3. Filtros OR (Solo Nivel Raíz)**
+ * ```typescript
+ * // ✅ OR simple a nivel raíz (soportado nativamente)
+ * const query = {
+ *   where: {
+ *     OR: [
+ *       { status: 'active' },
+ *       { status: 'pending' }
+ *     ]
+ *   }
+ * }
+ *
+ * const baserowQuery = PrismaBaserowMapper.transformPrismaToBaserow(query)
+ * // Genera: filter__status__equal=active&filter__status__equal=pending&filter_type=OR
+ * ```
+ *
+ * **4. Selección de Campos (Optimizar Transferencia)**
+ * ```typescript
+ * // Solo traer campos necesarios
+ * const query = {
+ *   where: { department: 'Sales' },
+ *   select: {
+ *     id: true,
+ *     name: true,
+ *     email: true,
+ *     password: false  // Excluir explícitamente
+ *   },
+ *   take: 50
+ * }
+ *
+ * const baserowQuery = PrismaBaserowMapper.transformPrismaToBaserow(query)
+ * // Genera: include=['id','name','email']&size=50
+ * ```
+ *
+ * **5. Migración desde Prisma ORM**
+ * ```typescript
+ * // Migrar query existente de Prisma
+ * const prismaQuery = await prisma.user.findMany({
+ *   where: { active: true },
+ *   orderBy: { createdAt: 'desc' },
+ *   take: 10,
+ *   skip: 20
+ * })
+ *
+ * // Equivalente en Baserow
+ * const baserowQuery = PrismaBaserowMapper.transformPrismaToBaserow({
+ *   where: { active: true },
+ *   orderBy: { createdAt: 'desc' },
+ *   take: 10,
+ *   skip: 20
+ * })
+ * const rows = await client.rows.list(tableId, baserowQuery)
+ * // Datos en formato similar a Prisma
+ * ```
+ *
+ * @aiLimitation
+ * ## ⚠️ Limitaciones de Baserow API
+ *
+ * **1. OR Anidado NO Soportado**
+ * ```typescript
+ * // ❌ INCORRECTO - OR anidado dentro de AND
+ * const complexOr = {
+ *   where: {
+ *     AND: [
+ *       { status: 'active' },
+ *       { OR: [{ age: { gt: 18 } }, { verified: true }] }  // ❌ NO funciona
+ *     ]
+ *   }
+ * }
+ * // Solución: Reestructurar query o filtrar client-side
+ * ```
+ *
+ * **2. IN/NOT IN con Múltiples Valores**
+ * ```typescript
+ * // ⚠️ LIMITADO - Solo usa el primer valor
+ * const query = {
+ *   where: {
+ *     status: { in: ['active', 'pending', 'processing'] }  // Solo usa 'active'
+ *   }
+ * }
+ * // Baserow API no soporta IN nativo, requiere client-side filtering
+ * ```
+ *
+ * **3. DISTINCT Client-Side Only**
+ * ```typescript
+ * // ⚠️ WARNING - distinct requiere post-procesamiento
+ * const query = {
+ *   distinct: ['department'],
+ *   where: { active: true }
+ * }
+ * // Genera warning: "Distinct is not directly supported by Baserow API"
+ * ```
+ *
+ * @aiMigrationFrom
+ * ## 🔄 Migración desde Prisma ORM
+ *
+ * **Mapeo de Operadores Prisma → Baserow:**
+ * - `equals` → `equal`
+ * - `not` → `not_equal`
+ * - `contains` → `contains`
+ * - `startsWith` → `starts_with`
+ * - `endsWith` → `ends_with`
+ * - `gt` → `higher_than`
+ * - `gte` → `higher_than_or_equal`
+ * - `lt` → `lower_than`
+ * - `lte` → `lower_than_or_equal`
+ * - `in` (múltiple) → ⚠️ Solo primer valor (limitación API)
+ * - `isEmpty` / `empty` → `empty`
+ * - `isNotEmpty` / `notEmpty` → `not_empty`
+ *
+ * **Conversiones Automáticas:**
+ * - Dates: `new Date()` → ISO string automáticamente
+ * - Select fields: `value` → `optionId` (con FieldMetadata)
+ * - Pagination: `take/skip` → `size/page`
+ * - OrderBy: `{ field: 'desc' }` → `-field`
+ *
+ * @aiPerformance
+ * ## ⚡ Optimizaciones de Query
+ *
+ * **1. Limitar Page Size Automáticamente**
+ * ```typescript
+ * // Si size > 1000, se limita a 1000 con warning
+ * const query = { take: 5000 }  // ⚠️ Muy grande
+ * const baserow = PrismaBaserowMapper.transformPrismaToBaserow(query)
+ * // Result: size=1000 (limitado automáticamente)
+ * ```
+ *
+ * **2. Usar Select para Reducir Payload**
+ * ```typescript
+ * // ✅ BUENO - Solo campos necesarios
+ * const optimized = {
+ *   select: { id: true, name: true },  // Solo 2 campos
+ *   take: 1000
+ * }
+ *
+ * // ❌ MALO - Todos los campos
+ * const heavy = {
+ *   take: 1000  // Trae TODOS los campos (payload grande)
+ * }
+ * ```
+ *
+ * **3. Analizar Complejidad de Query**
+ * ```typescript
+ * const analysis = PrismaBaserowMapper.analyzeQueryComplexity(query)
+ * console.log(`Score: ${analysis.score}`)  // Score alto = query compleja
+ * console.log('Warnings:', analysis.warnings)  // Problemas potenciales
+ * console.log('Suggestions:', analysis.suggestions)  // Optimizaciones sugeridas
+ * ```
+ *
+ * **4. Evitar OR Operators (Mejor Performance)**
+ * ```typescript
+ * // ⚡ RÁPIDO - Filtros AND (procesamiento server-side)
+ * const fast = {
+ *   where: {
+ *     AND: [{ status: 'active' }, { verified: true }]
+ *   }
+ * }
+ *
+ * // 🐌 LENTO - OR operators (puede requerir client-side)
+ * const slow = {
+ *   where: {
+ *     OR: [{ status: 'active' }, { status: 'pending' }]
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const prismaOptions = {
+ *   where: { status: 'active', age: { gte: 18 } },
+ *   orderBy: { created_at: 'desc' },
+ *   take: 20,
+ *   skip: 0
+ * }
+ *
+ * const baserowOptions = PrismaBaserowMapper.transformPrismaToBaserow(prismaOptions)
+ * // Result: { filters: { status: 'active', age__gte: 18 }, order_by: '-created_at', size: 20, page: 1 }
+ * ```
+ *
+ * @since 1.1.0
+ */
+export class PrismaBaserowMapper {
+  /**
+   * Transformar opciones Prisma completas a formato Baserow API
+   *
+   * Convierte una consulta estilo Prisma en opciones compatibles con
+   * la API de Baserow, aplicando todas las transformaciones necesarias
+   * y optimizaciones automáticas.
+   *
+   * @param options - Opciones de consulta estilo Prisma
+   * @returns Opciones convertidas para Baserow API
+   *
+   * @example
+   * ```typescript
+   * const result = PrismaBaserowMapper.transformPrismaToBaserow({
+   *   where: {
+   *     AND: [
+   *       { status: 'active' },
+   *       { age: { gte: 18, lt: 65 } }
+   *     ]
+   *   },
+   *   orderBy: [{ created_at: 'desc' }, { name: 'asc' }],
+   *   take: 10,
+   *   skip: 20,
+   *   select: { id: true, name: true, password: false }
+   * })
+   * ```
+   *
+   * @since 1.2.0
+   */
+  static transformPrismaToBaserow(options?: PrismaLikeQueryOptions, fieldMetadata?: FieldMetadata): QueryOptions {
+    if (!options) return {}
+
+    const baserowOptions: QueryOptions = {}
+
+    // Transformar paginación: take/skip → size/page
+    const pagination = this.transformPagination(options.take, options.skip)
+    Object.assign(baserowOptions, pagination)
+
+    // Transformar filtros: where → aplanar filtros directamente
+    if (options.where) {
+      const filters = this.transformWhereToFilters(options.where, fieldMetadata)
+      Object.assign(baserowOptions, filters)
+
+      // Detectar si hay operador OR a nivel raíz y agregar filter_type
+      if (this.hasRootOrOperator(options.where)) {
+        baserowOptions.filter_type = 'OR'
+      }
+    }
+
+    // Transformar ordenamiento: orderBy → order_by
+    if (options.orderBy) {
+      baserowOptions.order_by = this.transformOrderByToBaserow(options.orderBy)
+    }
+
+    // Transformar selección: select → include/exclude
+    if (options.select) {
+      const fieldSelection = this.transformSelectToFields(options.select)
+      Object.assign(baserowOptions, fieldSelection)
+    }
+
+    // Transformar distinct
+    if (options.distinct && options.distinct.length > 0) {
+      // Baserow no soporta distinct directamente, pero podemos documentarlo
+      // eslint-disable-next-line no-console
+      console.warn('Distinct is not directly supported by Baserow API, filtering will be done client-side')
+      baserowOptions.distinct = options.distinct as string[]
+    }
+
+    // Opciones específicas de Baserow
+    baserowOptions.user_field_names = options.userFieldNames ?? true
+
+    return this.validateAndOptimize(baserowOptions)
+  }
+
+  /**
+   * Convertir valor a string compatible con Baserow API
+   *
+   * @param value - Valor a convertir
+   * @returns String compatible con Baserow
+   */
+  private static valueToString(value: any): string {
+    if (value instanceof Date) {
+      return value.toISOString()
+    }
+    if (value === null) {
+      return 'null'
+    }
+    if (value === undefined) {
+      return 'undefined'
+    }
+    return String(value)
+  }
+
+  /**
+   * Transformar cláusula WHERE a filtros Baserow
+   *
+   * Convierte la sintaxis de filtrado estilo Prisma a los filtros query parameters
+   * que espera la API de Baserow usando el formato:
+   * filter__field__type=value
+   *
+   * @param where - Cláusula WHERE estilo Prisma
+   * @returns Record de filtros compatible con Baserow API
+   *
+   * @example
+   * ```typescript
+   * const filters = PrismaBaserowMapper.transformWhereToFilters({
+   *   name: 'John',
+   *   age: { gte: 18, lt: 65 },
+   *   email: { contains: '@company.com' }
+   * })
+   * // Result: {
+   * //   "filter__name__equal": "John",
+   * //   "filter__age__higher_than_or_equal": "18",
+   * //   "filter__age__lower_than": "65",
+   * //   "filter__email__contains": "@company.com"
+   * // }
+   * ```
+   *
+   * @since 1.2.0
+   */
+  static transformWhereToFilters(where?: WhereClause, fieldMetadata?: FieldMetadata): Record<string, any> {
+    if (!where) return {}
+
+    const filters: Record<string, any> = {}
+
+    for (const [key, value] of Object.entries(where)) {
+      // Operadores lógicos especiales
+      if (key === 'AND') {
+        // Combinar múltiples condiciones AND
+        const andFilters = (value as WhereClause[]).map(clause => this.transformWhereToFilters(clause, fieldMetadata))
+        // Fusionar todos los filtros AND (aplican todos)
+        andFilters.forEach(filterObj => Object.assign(filters, filterObj))
+        continue
+      }
+
+      if (key === 'OR') {
+        // Baserow soporta OR mediante filter_type=OR (solo a nivel raíz flat)
+        // Aplanar filtros OR - el filter_type se agregará en transformPrismaToBaserow
+        const orFilters = (value as WhereClause[]).map(clause => this.transformWhereToFilters(clause, fieldMetadata))
+
+        // Verificar si hay múltiples campos en el OR (simple) o AND anidados (complejo)
+        const hasNestedOperators = orFilters.some(f =>
+          Object.keys(f).some(k => k.includes('__') && Object.keys(f).length > 1)
+        )
+
+        if (hasNestedOperators) {
+          // eslint-disable-next-line no-console
+          console.warn(
+            'Complex OR with multiple conditions per branch may not work as expected. Baserow OR only supports flat filters.'
+          )
+        }
+
+        orFilters.forEach(filterObj => Object.assign(filters, filterObj))
+        continue
+      }
+
+      if (key === 'NOT') {
+        // Implementar NOT usando operadores de negación
+        const notFilters = this.transformWhereToFilters(value as WhereClause, fieldMetadata)
+        for (const [filterKey, filterValue] of Object.entries(notFilters)) {
+          // Convertir tipo a versión negativa
+          const negatedKey = this.negateFilterKey(filterKey)
+          filters[negatedKey] = filterValue
+        }
+        continue
+      }
+
+      // Operadores de campo (excluir Date que debe tratarse como valor simple)
+      if (typeof value === 'object' && value !== null && !Array.isArray(value) && !(value instanceof Date)) {
+        const operators = value as FieldOperators
+        const fieldType = fieldMetadata?.types[key] || 'text'
+
+        if ('equals' in operators) {
+          this.addFieldFilter(filters, key, fieldType, 'equal', operators.equals, fieldMetadata?.selectOptions)
+        }
+        if ('not' in operators) {
+          this.addFieldFilter(filters, key, fieldType, 'not_equal', operators.not, fieldMetadata?.selectOptions)
+        }
+        if ('contains' in operators) {
+          this.addFieldFilter(filters, key, fieldType, 'contains', operators.contains, fieldMetadata?.selectOptions)
+        }
+        if ('contains_not' in operators) {
+          filters[`filter__${key}__contains_not`] = this.valueToString(operators.contains_not)
+        }
+        if ('startsWith' in operators) {
+          filters[`filter__${key}__starts_with`] = this.valueToString(operators.startsWith)
+        }
+        if ('endsWith' in operators) {
+          filters[`filter__${key}__ends_with`] = this.valueToString(operators.endsWith)
+        }
+        if ('gt' in operators) {
+          filters[`filter__${key}__higher_than`] = this.valueToString(operators.gt)
+        }
+        if ('gte' in operators) {
+          filters[`filter__${key}__higher_than_or_equal`] = this.valueToString(operators.gte)
+        }
+        if ('lt' in operators) {
+          filters[`filter__${key}__lower_than`] = this.valueToString(operators.lt)
+        }
+        if ('lte' in operators) {
+          filters[`filter__${key}__lower_than_or_equal`] = this.valueToString(operators.lte)
+        }
+        if ('in' in operators) {
+          const values = Array.isArray(operators.in) ? operators.in : [operators.in]
+          // Filtrar valores vacíos o undefined
+          const validValues = values.filter(v => v !== undefined && v !== null && v !== '')
+          if (validValues.length === 1) {
+            filters[`filter__${key}__equal`] = this.valueToString(validValues[0])
+          } else if (validValues.length > 1) {
+            // eslint-disable-next-line no-console
+            console.warn('IN with multiple values requires client-side filtering in Baserow')
+            filters[`filter__${key}__equal`] = this.valueToString(validValues[0]) // Usar solo el primero
+          }
+          // Si no hay valores válidos, no crear filtro
+        }
+        if ('notIn' in operators) {
+          const values = Array.isArray(operators.notIn) ? operators.notIn : [operators.notIn]
+          // Filtrar valores vacíos o undefined
+          const validValues = values.filter(v => v !== undefined && v !== null && v !== '')
+          if (validValues.length === 1) {
+            filters[`filter__${key}__not_equal`] = this.valueToString(validValues[0])
+          } else if (validValues.length > 1) {
+            // eslint-disable-next-line no-console
+            console.warn('NOT IN with multiple values requires client-side filtering in Baserow')
+            filters[`filter__${key}__not_equal`] = this.valueToString(validValues[0]) // Usar solo el primero
+          }
+          // Si no hay valores válidos, no crear filtro
+        }
+        // Soporte para isEmpty y su alias empty (sintaxis Baserow)
+        if (('isEmpty' in operators && operators.isEmpty) || ('empty' in operators && operators.empty)) {
+          filters[`filter__${key}__empty`] = ''
+        }
+        // Soporte para isNotEmpty y su alias notEmpty (sintaxis Baserow)
+        if (('isNotEmpty' in operators && operators.isNotEmpty) || ('notEmpty' in operators && operators.notEmpty)) {
+          filters[`filter__${key}__not_empty`] = ''
+        }
+      } else {
+        // Valor simple (equals implícito)
+        const fieldType = fieldMetadata?.types[key] || 'text'
+        this.addFieldFilter(filters, key, fieldType, 'equal', value, fieldMetadata?.selectOptions)
+      }
+    }
+
+    return filters
+  }
+
+  /**
+   * Negar una clave de filtro de Baserow
+   *
+   * @param filterKey - Clave de filtro a negar (formato filter__field__type)
+   * @returns Clave de filtro negada
+   */
+  private static negateFilterKey(filterKey: string): string {
+    const negationMap: Record<string, string> = {
+      equal: 'not_equal',
+      not_equal: 'equal',
+      contains: 'contains_not',
+      contains_not: 'contains',
+      higher_than: 'lower_than_or_equal',
+      lower_than: 'higher_than_or_equal',
+      higher_than_or_equal: 'lower_than',
+      lower_than_or_equal: 'higher_than',
+      empty: 'not_empty',
+      not_empty: 'empty'
+    }
+
+    // Parsear la clave: filter__field__type
+    const parts = filterKey.split('__')
+    if (parts.length === 3 && parts[0] === 'filter') {
+      const [, field, filterType] = parts
+      const negatedType = negationMap[filterType] || `not_${filterType}`
+      return `filter__${field}__${negatedType}`
+    }
+
+    return filterKey // Si no puede parsear, devolver original
+  }
+
+  /**
+   * Transformar configuración orderBy a string order_by de Baserow
+   *
+   * Convierte la configuración de ordenamiento estilo Prisma a la
+   * sintaxis de string que espera la API de Baserow, soportando
+   * ordenamiento por múltiples campos.
+   *
+   * @param orderBy - Configuración de ordenamiento Prisma
+   * @returns String de ordenamiento para Baserow API
+   *
+   * @example
+   * ```typescript
+   * // Ordenamiento simple
+   * const result1 = PrismaBaserowMapper.transformOrderByToBaserow({ name: 'asc' })
+   * // Result: 'name'
+   *
+   * // Ordenamiento múltiple
+   * const result2 = PrismaBaserowMapper.transformOrderByToBaserow([
+   *   { created_at: 'desc' },
+   *   { name: 'asc' }
+   * ])
+   * // Result: '-created_at,name'
+   * ```
+   *
+   * @since 1.2.0
+   */
+  static transformOrderByToBaserow(orderBy?: OrderByClause): string | undefined {
+    if (!orderBy) return undefined
+
+    const orders: string[] = []
+
+    if (Array.isArray(orderBy)) {
+      // Múltiples campos de ordenamiento
+      for (const orderItem of orderBy) {
+        for (const [field, direction] of Object.entries(orderItem)) {
+          const prefix = direction === 'desc' ? '-' : ''
+          orders.push(`${prefix}${field}`)
+        }
+      }
+    } else {
+      // Un solo objeto de ordenamiento
+      for (const [field, direction] of Object.entries(orderBy)) {
+        const prefix = direction === 'desc' ? '-' : ''
+        orders.push(`${prefix}${field}`)
+      }
+    }
+
+    return orders.length > 0 ? orders.join(',') : undefined
+  }
+
+  /**
+   * Transformar configuración select a include/exclude de Baserow
+   *
+   * Convierte la selección de campos estilo Prisma a los arrays
+   * include/exclude que utiliza la API de Baserow para filtrar campos.
+   *
+   * @param select - Configuración de selección Prisma
+   * @returns Objeto con arrays include/exclude para Baserow
+   *
+   * @example
+   * ```typescript
+   * const result = PrismaBaserowMapper.transformSelectToFields({
+   *   id: true,
+   *   name: true,
+   *   email: true,
+   *   password: false,
+   *   internal_notes: false
+   * })
+   * // Result: { include: ['id', 'name', 'email'] }
+   * ```
+   *
+   * @since 1.2.0
+   */
+  static transformSelectToFields(select?: SelectClause): { include?: string[]; exclude?: string[] } {
+    if (!select) return {}
+
+    const include: string[] = []
+    const exclude: string[] = []
+
+    for (const [field, selected] of Object.entries(select)) {
+      if (selected === true) {
+        include.push(field)
+      } else if (selected === false) {
+        exclude.push(field)
+      }
+    }
+
+    // Estrategia: si hay campos incluidos, usar include. Si no, usar exclude
+    if (include.length > 0) {
+      return { include }
+    } else if (exclude.length > 0) {
+      return { exclude }
+    }
+
+    return {}
+  }
+
+  /**
+   * Transformar take/skip a page/size de Baserow
+   *
+   * Convierte la paginación estilo Prisma (take/skip) al formato
+   * page/size que utiliza la API de Baserow.
+   *
+   * @param take - Número máximo de registros (equivale a size)
+   * @param skip - Número de registros a saltar
+   * @returns Objeto con page/size para Baserow
+   *
+   * @example
+   * ```typescript
+   * const result = PrismaBaserowMapper.transformPagination(20, 40)
+   * // Result: { size: 20, page: 3 }  // skip 40 with size 20 = page 3
+   * ```
+   *
+   * @since 1.2.0
+   */
+  static transformPagination(take?: number, skip?: number): { page?: number; size?: number } {
+    const result: { page?: number; size?: number } = {}
+
+    if (take !== undefined) {
+      result.size = take
+    }
+
+    if (skip !== undefined && take !== undefined && take > 0) {
+      result.page = Math.floor(skip / take) + 1
+    } else if (skip !== undefined) {
+      // Si solo hay skip sin take, asumir size por defecto
+      const defaultSize = 100
+      result.size = defaultSize
+      result.page = Math.floor(skip / defaultSize) + 1
+    }
+
+    return result
+  }
+
+  /**
+   * Validar y optimizar consulta final
+   *
+   * Aplica validaciones y optimizaciones automáticas a las opciones
+   * de consulta convertidas para mejorar rendimiento y evitar errores.
+   *
+   * @param options - Opciones de consulta a optimizar
+   * @returns Opciones optimizadas y validadas
+   *
+   * @example
+   * ```typescript
+   * const optimized = PrismaBaserowMapper.validateAndOptimize({
+   *   page: 0,      // Se corrige a 1
+   *   size: 2000,   // Se limita a 1000
+   *   filters: {},  // Se elimina
+   *   include: []   // Se elimina
+   * })
+   * // Result: { page: 1, size: 1000 }
+   * ```
+   *
+   * @since 1.2.0
+   */
+  static validateAndOptimize(options: QueryOptions): QueryOptions {
+    const optimized = { ...options }
+
+    // Validar paginación
+    if (optimized.page !== undefined && optimized.page < 1) {
+      optimized.page = 1
+    }
+
+    if (optimized.size !== undefined && optimized.size > 1000) {
+      // eslint-disable-next-line no-console
+      console.warn('Large page size detected, limiting to 1000. Consider using pagination.')
+      optimized.size = 1000
+    }
+
+    if (optimized.size !== undefined && optimized.size < 1) {
+      optimized.size = 1
+    }
+
+    // Limpiar filtros vacíos
+    if (optimized.filters && Object.keys(optimized.filters).length === 0) {
+      delete optimized.filters
+    }
+
+    // Limpiar arrays vacíos
+    if (optimized.include && optimized.include.length === 0) {
+      delete optimized.include
+    }
+    if (optimized.exclude && optimized.exclude.length === 0) {
+      delete optimized.exclude
+    }
+    if (optimized.distinct && optimized.distinct.length === 0) {
+      delete optimized.distinct
+    }
+
+    // Validar conflictos include/exclude
+    if (optimized.include && optimized.exclude) {
+      // eslint-disable-next-line no-console
+      console.warn('Both include and exclude specified, using include only')
+      delete optimized.exclude
+    }
+
+    return optimized
+  }
+
+  /**
+   * Crear where clause a partir de filtros legacy de Baserow
+   *
+   * Función de utilidad para convertir en dirección opuesta:
+   * de filtros Baserow existentes a sintaxis where de Prisma.
+   *
+   * @param filters - Filtros en formato Baserow
+   * @returns Cláusula WHERE estilo Prisma
+   *
+   * @example
+   * ```typescript
+   * const where = PrismaBaserowMapper.transformFiltersToWhere({
+   *   name: 'John',
+   *   age__gte: 18,
+   *   email__contains: '@company.com'
+   * })
+   * // Result: { name: 'John', age: { gte: 18 }, email: { contains: '@company.com' } }
+   * ```
+   *
+   * @since 1.2.0
+   */
+  static transformFiltersToWhere(filters?: Record<string, any>): WhereClause {
+    if (!filters) return {}
+
+    const where: WhereClause = {}
+
+    for (const [key, value] of Object.entries(filters)) {
+      // Detectar operadores Baserow y convertir a Prisma
+      if (key.includes('__')) {
+        const [field, operator] = key.split('__', 2)
+
+        if (!where[field] || typeof where[field] !== 'object') {
+          where[field] = {}
+        }
+        const fieldWhere = where[field] as any
+
+        switch (operator) {
+          case 'contains':
+            fieldWhere.contains = value
+            break
+          case 'startswith':
+            fieldWhere.startsWith = value
+            break
+          case 'endswith':
+            fieldWhere.endsWith = value
+            break
+          case 'gt':
+            fieldWhere.gt = value
+            break
+          case 'gte':
+            fieldWhere.gte = value
+            break
+          case 'lt':
+            fieldWhere.lt = value
+            break
+          case 'lte':
+            fieldWhere.lte = value
+            break
+          case 'in':
+            fieldWhere.in = typeof value === 'string' ? value.split(',') : value
+            break
+          case 'not_in':
+            fieldWhere.notIn = typeof value === 'string' ? value.split(',') : value
+            break
+          case 'not':
+            fieldWhere.not = value
+            break
+          case 'empty':
+            fieldWhere.isEmpty = Boolean(value)
+            break
+          case 'not_empty':
+            fieldWhere.isNotEmpty = Boolean(value)
+            break
+          default:
+            // Operador no reconocido, mantener como filtro legacy
+            where[key] = value
+        }
+      } else {
+        // Campo simple sin operador
+        where[key] = value
+      }
+    }
+
+    return where
+  }
+
+  /**
+   * Detectar si hay operador OR a nivel raíz (para filter_type)
+   *
+   * Verifica si la consulta tiene un operador OR en el nivel raíz,
+   * lo cual permite usar filter_type=OR en Baserow API.
+   *
+   * @param where - Cláusula WHERE a analizar
+   * @returns true si contiene OR a nivel raíz
+   *
+   * @since 1.3.0
+   */
+  static hasRootOrOperator(where?: WhereClause): boolean {
+    if (!where) return false
+    return where.OR !== undefined && Array.isArray(where.OR) && where.OR.length > 0
+  }
+
+  /**
+   * Detectar si hay operadores OR en la consulta (incluye anidados)
+   *
+   * Utilidad para verificar si una consulta contiene operadores OR
+   * que requieren procesamiento especial en el cliente.
+   *
+   * @param where - Cláusula WHERE a analizar
+   * @returns true si contiene operadores OR
+   *
+   * @since 1.2.0
+   */
+  static hasOrOperators(where?: WhereClause): boolean {
+    if (!where) return false
+
+    if (where.OR && Array.isArray(where.OR) && where.OR.length > 0) {
+      return true
+    }
+
+    // Buscar OR anidados
+    for (const value of Object.values(where)) {
+      if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        if (this.hasOrOperators(value as WhereClause)) {
+          return true
+        }
+      }
+    }
+
+    return false
+  }
+
+  /**
+   * Estimar complejidad de la consulta
+   *
+   * Analiza una consulta para determinar su complejidad y
+   * sugerir optimizaciones si es necesario.
+   *
+   * @param options - Opciones de consulta a analizar
+   * @returns Métricas de complejidad
+   *
+   * @since 1.2.0
+   */
+  static analyzeQueryComplexity(options?: PrismaLikeQueryOptions): {
+    score: number
+    warnings: string[]
+    suggestions: string[]
+  } {
+    const warnings: string[] = []
+    const suggestions: string[] = []
+    let score = 0
+
+    if (!options) return { score: 0, warnings, suggestions }
+
+    // Analizar filtros
+    if (options.where) {
+      const filterCount = Object.keys(options.where).length
+      score += filterCount
+
+      if (this.hasOrOperators(options.where)) {
+        score += 5
+        warnings.push('OR operators require client-side processing')
+        suggestions.push('Consider restructuring query to avoid OR operators')
+      }
+
+      if (filterCount > 10) {
+        warnings.push('High number of filters may impact performance')
+        suggestions.push('Consider using fewer, more specific filters')
+      }
+    }
+
+    // Analizar paginación
+    if (options.take && options.take > 500) {
+      score += 3
+      warnings.push('Large page size may impact performance')
+      suggestions.push('Consider using smaller page sizes with pagination')
+    }
+
+    // Analizar ordenamiento
+    if (options.orderBy) {
+      const orderCount = Array.isArray(options.orderBy) ? options.orderBy.length : 1
+      score += orderCount
+      if (orderCount > 3) {
+        warnings.push('Multiple order fields may impact performance')
+      }
+    }
+
+    return { score, warnings, suggestions }
+  }
+
+  /**
+   * Agregar filtro específico según tipo de campo con resolución automática value → ID
+   *
+   * @private
+   * @param filters - Objeto de filtros a modificar
+   * @param fieldName - Nombre del campo
+   * @param fieldType - Tipo del campo (text, single_select, etc.)
+   * @param operator - Operador lógico (equal, contains, etc.)
+   * @param value - Valor del filtro
+   * @param selectOptions - Mapa de opciones select para resolución value → ID
+   */
+  private static addFieldFilter(
+    filters: Record<string, any>,
+    fieldName: string,
+    fieldType: string,
+    operator: string,
+    value: any,
+    selectOptions?: Record<string, Record<string, number>>
+  ): void {
+    let baserowOperator: string
+    let resolvedValue = value
+
+    // Resolver value → ID para campos select automáticamente
+    if (['single_select', 'multiple_select'].includes(fieldType)) {
+      const fieldOptions = selectOptions?.[fieldName]
+      if (fieldOptions && typeof value === 'string') {
+        const optionId = fieldOptions[value]
+        if (optionId !== undefined) {
+          resolvedValue = optionId
+        }
+      }
+    }
+
+    // Mapear operadores específicos por tipo de campo
+    switch (fieldType) {
+      case 'single_select':
+        baserowOperator = operator === 'equal' ? 'single_select_equal' : `single_select_${operator}`
+        break
+      case 'multiple_select':
+        // Para multiple_select, mapear operadores específicos
+        if (operator === 'equal' || operator === 'contains') {
+          baserowOperator = 'multiple_select_has'
+        } else {
+          baserowOperator = `multiple_select_${operator}`
+        }
+        break
+      default:
+        // Para campos normales, usar operador estándar
+        baserowOperator = operator
+    }
+
+    filters[`filter__${fieldName}__${baserowOperator}`] = this.valueToString(resolvedValue)
+  }
+}