@gzl10/baserow 1.2.0

package/src/contexts/TableContext.ts

@@ -0,0 +1,1247 @@
+import {
+  Logger,
+  Database,
+  Table,
+  Field,
+  Row,
+  BaserowNotFoundError,
+  CreateTableRequest,
+  SelectOption,
+  NumberSeparator,
+  RatingStyle,
+  RatingColor,
+  QueryOptions,
+  PrismaLikeQueryOptions,
+  WhereClause,
+  SelectClause,
+  FieldAdvancedOptions,
+  FieldType,
+  CreateFieldByType
+} from '../types'
+import { WorkspaceService } from '../services/WorkspaceService'
+import { DatabaseService } from '../services/DatabaseService'
+import { TableService } from '../services/TableService'
+import { FieldService } from '../services/FieldService'
+import { RowService } from '../services/RowService'
+import { FieldContext } from './FieldContext'
+import { RowOnlyContext } from './RowContext'
+import { PrismaBaserowMapper } from '../utils/prisma-mapper'
+import { FieldCache } from '../utils/field-cache'
+import { validateRequired } from '../utils/validation'
+
+/**
+ * Context para operaciones en una tabla específica
+ *
+ * Proporciona una API jerárquica fluida para operaciones administrativas
+ * dentro de una tabla específica. Es el nivel más granular de la API
+ * jerárquica y permite operaciones completas de campos y filas.
+ *
+ * **Características principales:**
+ * - Resolución automática de tabla por nombre o ID (lazy loading)
+ * - API fluida para 21 tipos de campos diferentes
+ * - Operaciones CRUD completas de filas con soporte bulk
+ * - Operaciones avanzadas: search, count, listAll
+ * - Cache interno para evitar resoluciones repetidas
+ * - Logging opcional de todas las operaciones
+ * - Validación automática de parámetros y tipos
+ *
+ * **Tipos de Campos Soportados (21/22):**
+ * - **Texto**: text, long_text, url, email, phone_number
+ * - **Numéricos**: number, boolean, rating
+ * - **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
+ *
+ * **Patrón de API Jerárquica:**
+ * ```
+ * table.field.createText('nombre')        // Crear campo
+ * table.field.list()                      // Listar campos
+ * table.rows.list()                       // Listar filas
+ * table.rows.createBulk([...])            // Operaciones bulk
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Operaciones de campos - todos los tipos soportados
+ * const textField = await table.field.createText('nombre')
+ * const numberField = await table.field.createNumber('precio', 2)
+ * const selectField = await table.field.createSelect('estado', [
+ *   { value: 'activo', color: 'blue' },
+ *   { value: 'inactivo', color: 'red' }
+ * ])
+ * const linkField = await table.field.createLink('productos', targetTableId)
+ *
+ * // Campos avanzados
+ * const fileField = await table.field.createFile('documentos')
+ * const rollupField = await table.field.createRollup('total', linkFieldId, priceFieldId, 'sum')
+ *
+ * // Operaciones de filas
+ * const rows = await table.rows.list({ page: 1, size: 100 })
+ * const newRow = await table.rows.create({ nombre: 'Juan', precio: 100 })
+ *
+ * // Operaciones bulk optimizadas
+ * const newRows = await table.rows.createBulk([
+ *   { nombre: 'Item 1', precio: 50 },
+ *   { nombre: 'Item 2', precio: 75 }
+ * ], { batchSize: 50 })
+ *
+ * // Búsqueda y agregaciones
+ * const found = await table.rows.search('texto a buscar')
+ * const count = await table.rows.count({ estado: 'activo' })
+ * const allRows = await table.rows.listAll() // Sin paginación
+ *
+ * // Gestión de la tabla
+ * await table.update({ name: 'Nuevo Nombre' })
+ * await table.delete()
+ * ```
+ *
+ * @since 1.0.0
+ */
+export class TableContext {
+  private tableIdentifier: string | number
+  private resolvedTable?: Table
+  private logger?: Logger
+  private fieldCache: FieldCache
+
+  /**
+   * Crea un nuevo context de tabla
+   *
+   * @param workspaceService - Servicio para operaciones de workspace
+   * @param workspaceIdentifier - Identificador del workspace padre (opcional)
+   * @param databaseIdentifier - Identificador de la database padre
+   * @param tableIdentifier - Nombre o ID de la tabla
+   * @param databaseService - Servicio para operaciones de database
+   * @param tableService - Servicio para operaciones de tabla
+   * @param fieldService - Servicio para operaciones de campos
+   * @param rowService - Servicio para operaciones de filas
+   * @param logger - Logger opcional para debug y trazabilidad
+   *
+   * @since 1.0.0
+   */
+  constructor(
+    private workspaceService: WorkspaceService,
+    private workspaceIdentifier: string | number | undefined,
+    private databaseIdentifier: string | number,
+    tableIdentifier: string | number,
+    private databaseService: DatabaseService,
+    private tableService: TableService,
+    private fieldService: FieldService,
+    private rowService: RowService,
+    logger?: Logger
+  ) {
+    this.tableIdentifier = tableIdentifier
+    this.logger = logger
+    this.fieldCache = new FieldCache(logger)
+  }
+
+  /**
+   * Obtener metadata completa de campos con cache
+   *
+   * @private
+   * @returns FieldMetadata con tipos y opciones select
+   */
+  private async getFieldMetadata() {
+    const table = await this.get()
+    return await this.fieldCache.getFieldMetadata(this.fieldService, table.id)
+  }
+
+  /**
+   * Acceder a un campo específico por nombre o ID
+   *
+   * Crea un context para operaciones específicas en un campo individual.
+   * Permite operaciones contextuales como update, delete y gestión avanzada
+   * de índices y restricciones con API intuitiva.
+   *
+   * **Operaciones Disponibles:**
+   * - **CRUD Específico**: update(), delete()
+   * - **Gestión Avanzada**: index(), constraint(), getConstraints()
+   *
+   * **Para Operaciones Masivas**: Usa `table.fields.*` para crear, listar, etc.
+   *
+   * @param fieldIdentifier - Nombre o ID del campo
+   * @returns Context de campo para operaciones específicas
+   *
+   * @example
+   * ```typescript
+   * // Operaciones específicas por campo
+   * await table.field('email').update({ description: 'Email corporativo' })
+   * await table.field('campo_obsoleto').delete()
+   * await table.field(123).update({ name: 'Nuevo Nombre' })
+   *
+   * // Gestión de índices (API intuitiva)
+   * await table.field('email').index(true)   // Habilitar índice
+   * await table.field('email').index(false)  // Deshabilitar índice
+   *
+   * // Gestión de restricciones (API intuitiva)
+   * await table.field('email').constraint({ type: 'unique', active: true })  // Agregar
+   * await table.field('email').constraint('unique')                          // Eliminar
+   * const constraints = await table.field('codigo').getConstraints()
+   *
+   * // Para crear campos usar table.fields.*
+   * const textField = await table.fields.createText('nombre')
+   * const numberField = await table.fields.createNumber('precio', 2)
+   * ```
+   *
+   * @since 1.1.0
+   */
+  field(fieldIdentifier: string | number): FieldContext {
+    return new FieldContext(
+      this.fieldService,
+      async () => {
+        const table = await this.get()
+        return table.id
+      },
+      fieldIdentifier,
+      this.logger
+    )
+  }
+
+  /**
+   * Acceder a una fila específica por ID
+   *
+   * Crea un context para operaciones específicas en una fila individual.
+   * Permite operaciones contextuales como get, update y delete sin necesidad
+   * de pasar el rowId en cada llamada.
+   *
+   * **Operaciones Disponibles:**
+   * - **CRUD Específico**: get(), update(), delete()
+   * - **Utilidades**: exists()
+   *
+   * **Para Operaciones Masivas**: Usa `table.rows.*` para crear, listar, bulk, etc.
+   *
+   * @param rowId - ID de la fila
+   * @returns Context de fila para operaciones específicas
+   *
+   * @example
+   * ```typescript
+   * // Operaciones específicas por fila
+   * const row = await table.row(123).get()
+   * await table.row(123).update({ name: 'Juan Carlos', active: true })
+   * await table.row(456).delete()
+   * const exists = await table.row(789).exists()
+   *
+   * // Para operaciones masivas usar table.rows.*
+   * const allRows = await table.rows.findMany()
+   * const newRow = await table.rows.create({ name: 'Ana' })
+   * await table.rows.createBulk([...])
+   * ```
+   *
+   * @since 1.1.0
+   */
+  row(rowId: number): RowOnlyContext {
+    return new RowOnlyContext(
+      async () => {
+        const table = await this.get()
+        return table.id
+      },
+      rowId,
+      this.rowService,
+      this.logger
+    )
+  }
+
+  /**
+   * API unificada completa de campos (fields operations) - Prisma-style + Métodos Especializados
+   *
+   * Proporciona la API completa para gestionar campos combinando:
+   * - **API Prisma-style**: findMany, findUnique, create (genérico con tipos dinámicos)
+   * - **API Especializada**: Todos los métodos createText, createNumber, etc. (20+ métodos)
+   *
+   * Esta es la **API principal recomendada** para trabajar con campos.
+   * Para operaciones CRUD básicas simples, usar `table.field.*`.
+   *
+   * **Características:**
+   * - **Prisma-style**: Consistencia con otros servicios (findMany, findUnique)
+   * - **Métodos Especializados**: API fluida por tipo de campo con parámetros tipados
+   * - **Tipos Dinámicos**: create() genérico con IntelliSense contextual
+   * - **21 Tipos de Campos**: Cobertura completa (95% de tipos Baserow)
+   *
+   * @returns Objeto con API unificada completa para operaciones de campos
+   *
+   * @example
+   * ```typescript
+   * // === API Prisma-style ===
+   * const allFields = await table.fields.findMany()
+   * const fieldByName = await table.fields.findUnique('precio')
+   * const fieldById = await table.fields.findUnique(123)
+   *
+   * // create() dinámico con IntelliSense contextual
+   * const dynamicField = await table.fields.create({
+   *   type: 'text',
+   *   name: 'titulo',
+   *   text_default: 'Sin título' // ✅ Solo opciones de texto
+   * })
+   *
+   * // === API Especializada ===
+   * const textField = await table.fields.createText('nombre', 'Default')
+   * const numberField = await table.fields.createNumber('precio', 2, true, 0, '$')
+   * const selectField = await table.fields.createSelect('estado', [
+   *   { value: 'activo', color: 'blue' },
+   *   { value: 'inactivo', color: 'red' }
+   * ])
+   * const ratingField = await table.fields.createRating('calificacion', 5, 'yellow', 'star')
+   * const linkField = await table.fields.createLink('productos', targetTableId)
+   * const rollupField = await table.fields.createRollup('total', linkId, fieldId, 'sum')
+   *
+   * // === Campos Avanzados ===
+   * const fileField = await table.fields.createFile('documentos')
+   * const autoField = await table.fields.createAutonumber('ticket_id')
+   * const countField = await table.fields.createCount('items_count', linkFieldId)
+   * ```
+   *
+   * @since 1.1.0
+   */
+  get fields() {
+    return {
+      /**
+       * Listar todos los campos de la tabla
+       *
+       * Obtiene todos los campos que pertenecen a esta tabla.
+       * Incluye metadatos completos de cada campo.
+       * Equivalente a `field.list()` pero con naming Prisma-style.
+       *
+       * @returns Promise con array de campos de la tabla
+       *
+       * @example
+       * ```typescript
+       * const fields = await table.fields.findMany()
+       * console.log(`Encontrados ${fields.length} campos`)
+       * fields.forEach(field => {
+       *   console.log(`${field.name} (ID: ${field.id}, Type: ${field.type})`)
+       * })
+       * ```
+       *
+       * @since 1.1.0
+       */
+      findMany: async (): Promise<Field[]> => {
+        const table = await this.get()
+        return await this.fieldService.findMany(table.id)
+      },
+
+      /**
+       * Buscar campo por ID o nombre en esta tabla
+       *
+       * Busca un campo específico por su ID o nombre dentro de la tabla.
+       * Útil para operaciones donde se conoce el identificador pero no se sabe si es ID o nombre.
+       * Retorna null si no se encuentra (no lanza error).
+       *
+       * @param identifier - ID numérico o nombre del campo a buscar
+       * @returns Promise con el campo encontrado o null si no existe
+       *
+       * @example
+       * ```typescript
+       * const fieldByName = await table.fields.findUnique('precio')
+       * const fieldById = await table.fields.findUnique(123)
+       *
+       * if (fieldByName) {
+       *   console.log(`Campo encontrado: ${fieldByName.id}`)
+       * } else {
+       *   console.log('Campo no encontrado')
+       * }
+       * ```
+       *
+       * @since 1.1.0
+       */
+      findUnique: async (identifier: string | number): Promise<Field | null> => {
+        const table = await this.get()
+        return await this.fieldService.findUnique(table.id, identifier)
+      },
+
+      /**
+       * Crear campo con API genérica y tipos dinámicos
+       *
+       * Crea un nuevo campo usando una API genérica que proporciona
+       * IntelliSense contextual y type safety basado en el tipo seleccionado.
+       * Cada tipo de campo expone solo las opciones relevantes.
+       *
+       * **Tipos Soportados con IntelliSense:**
+       * - `text`, `long_text`, `url`, `email`, `phone_number`
+       * - `number`, `boolean`, `rating`
+       * - `date`, `last_modified`, `created_on`, etc.
+       * - `single_select`, `multiple_select`
+       * - `link_row`, `formula`
+       * - `file`, `autonumber`, `count`, `rollup`, `lookup`
+       *
+       * @param data - Configuración del campo con tipos dinámicos
+       * @returns Promise con el campo creado
+       *
+       * @throws {BaserowValidationError} Si los datos son inválidos
+       * @throws {BaserowNotFoundError} Si la tabla no existe
+       *
+       * @example
+       * ```typescript
+       * // Campo de texto con valor por defecto
+       * const textField = await table.fields.create({
+       *   type: 'text',
+       *   name: 'titulo',
+       *   text_default: 'Sin título',
+       *   description: 'Título del artículo'
+       * })
+       *
+       * // Campo numérico con formato de moneda
+       * const priceField = await table.fields.create({
+       *   type: 'number',
+       *   name: 'precio',
+       *   number_decimal_places: 2,
+       *   number_prefix: '$',
+       *   number_negative: false
+       * })
+       *
+       * // Campo de selección con opciones
+       * const statusField = await table.fields.create({
+       *   type: 'single_select',
+       *   name: 'estado',
+       *   select_options: [
+       *     { value: 'activo', color: 'blue' },
+       *     { value: 'pendiente', color: 'yellow' },
+       *     { value: 'cancelado', color: 'red' }
+       *   ]
+       * })
+       *
+       * // Campo de relación a otra tabla
+       * const linkField = await table.fields.create({
+       *   type: 'link_row',
+       *   name: 'productos',
+       *   link_row_table_id: 456
+       * })
+       *
+       * // Campo con índice y restricciones (v1.35+)
+       * const codeField = await table.fields.create({
+       *   type: 'text',
+       *   name: 'codigo',
+       *   index: true,
+       *   constraints: [
+       *     { type: 'unique', active: true }
+       *   ]
+       * })
+       * ```
+       *
+       * @since 1.1.0
+       */
+      create: async <T extends FieldType>(data: CreateFieldByType<T>): Promise<Field> => {
+        const table = await this.get()
+        return await this.fieldService.create(table.id, data as any)
+      },
+
+      // === MÉTODOS ESPECIALIZADOS DE CREACIÓN ===
+
+      // Campos básicos
+      createText: async (
+        name: string,
+        defaultValue?: string,
+        description?: string,
+        advancedOptions?: FieldAdvancedOptions
+      ) => {
+        const table = await this.get()
+        return await this.fieldService.createTextField(table.id, name, defaultValue, description, advancedOptions)
+      },
+
+      createLongText: async (name: string, defaultValue?: string, description?: string) => {
+        const table = await this.get()
+        if (description !== undefined) {
+          return await this.fieldService.createLongTextField(table.id, name, defaultValue, description)
+        } else if (defaultValue !== undefined) {
+          return await this.fieldService.createLongTextField(table.id, name, defaultValue)
+        } else {
+          return await this.fieldService.createLongTextField(table.id, name)
+        }
+      },
+
+      createUrl: async (name: string, description?: string) => {
+        const table = await this.get()
+        if (description !== undefined) {
+          return await this.fieldService.createUrlField(table.id, name, description)
+        } else {
+          return await this.fieldService.createUrlField(table.id, name)
+        }
+      },
+
+      createEmail: async (name: string, description?: string, advancedOptions?: FieldAdvancedOptions) => {
+        const table = await this.get()
+        return await this.fieldService.createEmailField(table.id, name, description, advancedOptions)
+      },
+
+      createPhoneNumber: async (name: string, defaultValue?: string, description?: string) => {
+        const table = await this.get()
+        return await this.fieldService.create(table.id, {
+          name,
+          type: 'phone_number',
+          text_default: defaultValue || '',
+          description
+        })
+      },
+
+      // Campos numéricos
+      createNumber: async (
+        name: string,
+        decimalPlaces = 0,
+        allowNegative = true,
+        defaultValue?: number,
+        prefix?: string,
+        suffix?: string,
+        separator: NumberSeparator = 'COMMA_PERIOD',
+        description?: string
+      ) => {
+        const table = await this.get()
+        return await this.fieldService.createNumberField(
+          table.id,
+          name,
+          decimalPlaces,
+          allowNegative,
+          defaultValue,
+          prefix,
+          suffix,
+          separator,
+          description
+        )
+      },
+
+      createBoolean: async (name: string, defaultValue = false, description?: string) => {
+        const table = await this.get()
+        return await this.fieldService.createBooleanField(table.id, name, defaultValue, description)
+      },
+
+      createRating: async (
+        name: string,
+        maxValue = 5,
+        color: RatingColor = 'yellow',
+        style: RatingStyle = 'star',
+        description?: string
+      ) => {
+        const table = await this.get()
+        return await this.fieldService.createRatingField(table.id, name, maxValue, color, style, description)
+      },
+
+      // Campos de fecha
+      createDate: async (
+        name: string,
+        includeTime = false,
+        dateFormat = 'ISO',
+        timeFormat = '24',
+        showTzInfo = false,
+        forceTimezone?: string,
+        forceTimezoneOffset?: number,
+        description?: string
+      ) => {
+        const table = await this.get()
+        return await this.fieldService.createDateField(
+          table.id,
+          name,
+          includeTime,
+          dateFormat,
+          timeFormat,
+          showTzInfo,
+          forceTimezone,
+          forceTimezoneOffset,
+          description
+        )
+      },
+
+      // Campos de selección
+      createSelect: async (name: string, options: SelectOption[], description?: string) => {
+        const table = await this.get()
+        return await this.fieldService.createSelectField(table.id, name, options, description)
+      },
+
+      createMultiSelect: async (name: string, options: SelectOption[], description?: string) => {
+        const table = await this.get()
+        return await this.fieldService.createMultiSelectField(table.id, name, options, description)
+      },
+
+      // Campos de relación
+      createLink: async (name: string, targetTableId: number, description?: string) => {
+        const table = await this.get()
+        return await this.fieldService.createLinkField(table.id, name, targetTableId, description)
+      },
+
+      createFormula: async (name: string, formula: string, description?: string) => {
+        const table = await this.get()
+        return await this.fieldService.createFormulaField(table.id, name, formula, description)
+      },
+
+      // Campos de auditoría
+      createLastModified: async (name: string, description?: string) => {
+        const table = await this.get()
+        return await this.fieldService.createLastModifiedField(table.id, name, description)
+      },
+
+      createLastModifiedBy: async (name: string, description?: string) => {
+        const table = await this.get()
+        return await this.fieldService.createLastModifiedByField(table.id, name, description)
+      },
+
+      createCreatedOn: async (name: string, description?: string) => {
+        const table = await this.get()
+        return await this.fieldService.createCreatedOnField(table.id, name, description)
+      },
+
+      createCreatedBy: async (name: string, description?: string) => {
+        const table = await this.get()
+        return await this.fieldService.createCreatedByField(table.id, name, description)
+      },
+
+      // Campos avanzados
+      createFile: async (name: string, description?: string) => {
+        const table = await this.get()
+        return await this.fieldService.createFileField(table.id, name, description)
+      },
+
+      createAutonumber: async (name: string, description?: string) => {
+        const table = await this.get()
+        return await this.fieldService.createAutonumberField(table.id, name, description)
+      },
+
+      createCount: async (name: string, throughFieldId: number, description?: string) => {
+        const table = await this.get()
+        return await this.fieldService.createCountField(table.id, name, throughFieldId, description)
+      },
+
+      createRollup: async (
+        name: string,
+        throughFieldId: number,
+        targetFieldId: number,
+        rollupFunction: string = 'sum',
+        description?: string
+      ) => {
+        const table = await this.get()
+        return await this.fieldService.createRollupField(
+          table.id,
+          name,
+          throughFieldId,
+          targetFieldId,
+          rollupFunction,
+          description
+        )
+      },
+
+      createLookup: async (name: string, throughFieldId: number, targetFieldId: number, description?: string) => {
+        const table = await this.get()
+        return await this.fieldService.createLookupField(table.id, name, throughFieldId, targetFieldId, description)
+      }
+    }
+  }
+
+  /**
+   * Rows - API para operaciones de masa y consultas de filas
+   *
+   * API para operaciones de masa en filas de esta tabla.
+   * Incluye operaciones estilo Prisma, búsqueda, filtrado y operaciones bulk.
+   * Para operaciones en filas específicas usar: table.row(id).operation()
+   *
+   * **Características principales:**
+   * - Operaciones estilo Prisma: findMany(), findUnique(), create()
+   * - Operaciones de masa: createMany(), updateMany(), deleteMany()
+   * - Búsqueda y filtrado: search(), count(), findAll()
+   * - Compatible con user field names
+   * - Control granular de webhook events
+   * - Paginación automática con findAll()
+   *
+   * @example
+   * ```typescript
+   * // Operaciones estilo Prisma
+   * const rows = await table.rows.findMany({ page: 1, size: 10 })
+   * const row = await table.rows.findUnique({ id: 123 })
+   * const newRow = await table.rows.create({
+   *   nombre: 'Juan Pérez',
+   *   email: 'juan@email.com',
+   *   activo: true
+   * })
+   *
+   * // Operaciones de masa optimizadas
+   * const newRows = await table.rows.createMany([
+   *   { nombre: 'Ana', email: 'ana@email.com' },
+   *   { nombre: 'Luis', email: 'luis@email.com' }
+   * ], { batchSize: 100, sendWebhookEvents: false })
+   *
+   * const updates = await table.rows.updateMany([
+   *   { id: 1, nombre: 'Ana Modificada' },
+   *   { id: 2, nombre: 'Luis Modificado' }
+   * ], { batchSize: 50 })
+   *
+   * await table.rows.deleteMany([1, 2, 3], { batchSize: 25 })
+   *
+   * // Búsqueda y agregaciones
+   * const found = await table.rows.search('juan', { order_by: 'nombre' })
+   * const count = await table.rows.count({ activo: true })
+   * const allRows = await table.rows.findAll({ filters: { estado: 'activo' } })
+   *
+   * // Para operaciones específicas usar API contextual:
+   * await table.row(123).update({ nombre: 'Juan Carlos' })
+   * await table.row(123).delete()
+   * const exists = await table.row(123).exists()
+   * ```
+   *
+   * @since 1.0.0
+   */
+  get rows() {
+    return {
+      // === MÉTODOS ESTILO PRISMA ===
+
+      /**
+       * Buscar múltiples filas con opciones avanzadas estilo Prisma
+       *
+       * Equivalente a Prisma findMany(), proporciona filtrado avanzado,
+       * ordenamiento, paginación y selección de campos con sintaxis familiar.
+       *
+       * @param options - Opciones de consulta estilo Prisma
+       * @returns Promise con array de filas que cumplen los criterios
+       *
+       * @example
+       * ```typescript
+       * // Consulta compleja estilo Prisma
+       * const users = await table.rows.findMany({
+       *   where: {
+       *     AND: [
+       *       { status: 'active' },
+       *       { age: { gte: 18, lt: 65 } }
+       *     ],
+       *     email: { contains: '@company.com' }
+       *   },
+       *   select: {
+       *     id: true,
+       *     name: true,
+       *     email: true
+       *   },
+       *   orderBy: [
+       *     { created_at: 'desc' },
+       *     { name: 'asc' }
+       *   ],
+       *   take: 20,
+       *   skip: 0
+       * })
+       *
+       * // Sintaxis legacy (compatible)
+       * const legacy = await table.rows.findMany({
+       *   filters: { status: 'active' },
+       *   size: 10,
+       *   order_by: '-created_at'
+       * })
+       * ```
+       *
+       * @since 1.2.0
+       */
+      findMany: async <T = Row>(options?: PrismaLikeQueryOptions<T>): Promise<T[]> => {
+        const table = await this.get()
+        const fieldMetadata = await this.getFieldMetadata()
+        const baserowOptions = PrismaBaserowMapper.transformPrismaToBaserow(options, fieldMetadata)
+        const response = await this.rowService.list(table.id, baserowOptions)
+        return response.rows as T[]
+      },
+
+      /**
+       * Buscar la primera fila que cumpla los criterios
+       *
+       * Equivalente a Prisma findFirst(), retorna la primera fila
+       * que coincida con los filtros especificados.
+       *
+       * @param options - Opciones de consulta estilo Prisma
+       * @returns Promise con la primera fila encontrada o null
+       *
+       * @example
+       * ```typescript
+       * const admin = await table.rows.findFirst({
+       *   where: {
+       *     role: 'admin',
+       *     status: 'active'
+       *   },
+       *   select: {
+       *     id: true,
+       *     name: true,
+       *     email: true
+       *   }
+       * })
+       * ```
+       *
+       * @since 1.2.0
+       */
+      findFirst: async <T = Row>(options?: PrismaLikeQueryOptions<T>): Promise<T | null> => {
+        const result = await this.rows.findMany({ ...options, take: 1 })
+        return (result[0] as T) || null
+      },
+
+      /**
+       * Buscar fila por ID único
+       *
+       * Equivalente a Prisma findUnique(), busca una fila específica
+       * por su ID con opciones de selección de campos.
+       *
+       * @param idOrWhere - ID de la fila o objeto con ID
+       * @param options - Opciones de selección y configuración
+       * @returns Promise con la fila encontrada o null
+       *
+       * @example
+       * ```typescript
+       * // Por ID directo:
+       * const user = await table.rows.findUnique(123)
+       *
+       * // Con objeto where:
+       * const user = await table.rows.findUnique({ id: 123 })
+       *
+       * // Con opciones:
+       * const user = await table.rows.findUnique(123, {
+       *   select: { id: true, name: true, email: true },
+       *   userFieldNames: true
+       * })
+       * ```
+       *
+       * @since 1.2.0
+       */
+      findUnique: async <T = Row>(
+        idOrWhere: number | { id: number },
+        options?: {
+          select?: SelectClause<T>
+          userFieldNames?: boolean
+        }
+      ): Promise<T | null> => {
+        try {
+          const table = await this.get()
+          const id = typeof idOrWhere === 'number' ? idOrWhere : idOrWhere.id
+          return (await this.rowService.get(table.id, id, options?.userFieldNames ?? true)) as T
+        } catch (error) {
+          if ((error as any).name === 'BaserowNotFoundError') {
+            return null
+          }
+          throw error
+        }
+      },
+
+      /**
+       * Contar filas que cumplen criterios específicos
+       *
+       * Equivalente a Prisma count(), cuenta filas sin cargar los datos.
+       * Más eficiente que findMany().length para obtener totales.
+       *
+       * @param options - Opciones con filtros WHERE
+       * @returns Promise con el número de filas que cumplen los criterios
+       *
+       * @example
+       * ```typescript
+       * const activeUsers = await table.rows.count({
+       *   where: {
+       *     status: 'active',
+       *     age: { gte: 18 }
+       *   }
+       * })
+       * ```
+       *
+       * @since 1.2.0
+       */
+      count: async <T = Row>(options?: { where?: WhereClause<T> | Record<string, any> }): Promise<number> => {
+        const table = await this.get()
+        const fieldMetadata = await this.getFieldMetadata()
+        const filters = PrismaBaserowMapper.transformWhereToFilters(options?.where, fieldMetadata)
+        return await this.rowService.count(table.id, filters)
+      },
+
+      // === MÉTODOS DE ESCRITURA ESTILO PRISMA ===
+
+      /**
+       * Crear nueva fila
+       *
+       * Equivalente a Prisma create(), crea una nueva fila con los datos
+       * proporcionados y retorna la fila creada.
+       *
+       * @param data - Datos de la nueva fila
+       * @returns Promise con la fila creada
+       *
+       * @example
+       * ```typescript
+       * const newUser = await table.rows.create({
+       *   name: 'John Doe',
+       *   email: 'john@company.com',
+       *   status: 'active'
+       * })
+       * ```
+       *
+       * @since 1.2.0
+       */
+      create: async <T = Row>(data: Partial<T>): Promise<T> => {
+        const table = await this.get()
+        return (await this.rowService.createRow(table.id, data)) as T
+      },
+
+      /**
+       * Crear múltiples filas en lote
+       *
+       * Equivalente a Prisma createMany(), crea múltiples filas
+       * de forma optimizada usando procesamiento en lotes.
+       *
+       * @param data - Array de datos para las nuevas filas
+       * @param options - Opciones de procesamiento en lotes
+       * @returns Promise con array de filas creadas
+       *
+       * @example
+       * ```typescript
+       * const newUsers = await table.rows.createMany([
+       *   { name: 'Alice', email: 'alice@company.com' },
+       *   { name: 'Bob', email: 'bob@company.com' }
+       * ], {
+       *   batchSize: 50,
+       *   skipDuplicates: true
+       * })
+       * ```
+       *
+       * @since 1.2.0
+       */
+      createMany: async <T = Row>(
+        data: Partial<T>[],
+        options?: {
+          skipDuplicates?: boolean
+          batchSize?: number
+          sendWebhookEvents?: boolean
+        }
+      ): Promise<T[]> => {
+        const table = await this.get()
+        return (await this.rowService.createBulk(table.id, data, {
+          batchSize: options?.batchSize,
+          send_webhook_events: options?.sendWebhookEvents
+        })) as T[]
+      },
+
+      /**
+       * Actualizar múltiples filas por ID
+       *
+       * Actualiza múltiples filas especificadas por ID de forma
+       * optimizada usando procesamiento en lotes.
+       *
+       * @param updates - Array con ID y datos a actualizar para cada fila
+       * @param options - Opciones de procesamiento en lotes
+       * @returns Promise con array de filas actualizadas
+       *
+       * @example
+       * ```typescript
+       * const updated = await table.rows.updateMany([
+       *   { id: 1, status: 'active' },
+       *   { id: 2, status: 'inactive' },
+       *   { id: 3, name: 'Updated Name' }
+       * ])
+       * ```
+       *
+       * @since 1.2.0
+       */
+      updateMany: async <T = Row>(
+        updates: Array<{ id: number } & Partial<T>>,
+        options?: {
+          batchSize?: number
+          sendWebhookEvents?: boolean
+        }
+      ): Promise<T[]> => {
+        const table = await this.get()
+        return (await this.rowService.updateBulk(table.id, updates, {
+          batchSize: options?.batchSize,
+          send_webhook_events: options?.sendWebhookEvents
+        })) as T[]
+      },
+
+      /**
+       * Eliminar múltiples filas por ID o criterios
+       *
+       * Elimina múltiples filas especificadas por ID o que cumplan
+       * criterios específicos de forma optimizada usando procesamiento en lotes.
+       *
+       * @param idsOrWhere - Array de IDs o objeto where con criterios
+       * @param options - Opciones de procesamiento en lotes
+       * @returns Promise que resuelve cuando se completa la eliminación
+       *
+       * @example
+       * ```typescript
+       * // Por IDs:
+       * await table.rows.deleteMany([1, 2, 3, 4, 5])
+       *
+       * // Por criterios (estilo Prisma):
+       * await table.rows.deleteMany({
+       *   where: { status: 'inactive', lastLogin: { lt: '2023-01-01' } }
+       * })
+       * ```
+       *
+       * @since 1.2.0
+       */
+      deleteMany: async <T = Row>(
+        idsOrWhere: number[] | { where: WhereClause<T> },
+        options?: { batchSize?: number }
+      ): Promise<void> => {
+        const table = await this.get()
+
+        if (Array.isArray(idsOrWhere)) {
+          // Eliminar por IDs
+          return await this.rowService.deleteBulk(table.id, idsOrWhere, options)
+        } else {
+          // Eliminar por criterios where - buscar IDs primero
+          const rowsToDelete = await this.rows.findMany({
+            where: idsOrWhere.where,
+            select: { id: true } as any
+          })
+          const ids = rowsToDelete.map((row: any) => row.id)
+          if (ids.length > 0) {
+            return await this.rowService.deleteBulk(table.id, ids, options)
+          }
+        }
+      },
+
+      // === MÉTODOS AVANZADOS ===
+
+      /**
+       * Buscar filas con texto libre (búsqueda global)
+       *
+       * Busca texto en todos los campos de la tabla.
+       * Útil para funcionalidades de búsqueda general.
+       *
+       * @param query - Texto a buscar
+       * @param options - Opciones adicionales (sin search)
+       * @returns Promise con filas que contienen el texto
+       *
+       * @example
+       * ```typescript
+       * const results = await table.rows.search('john@company.com', {
+       *   orderBy: { created_at: 'desc' },
+       *   take: 10
+       * })
+       * ```
+       *
+       * @since 1.2.0
+       */
+      search: async <T = Row>(query: string, options?: Omit<PrismaLikeQueryOptions<T>, 'where'>): Promise<T[]> => {
+        const table = await this.get()
+        const fieldMetadata = await this.getFieldMetadata()
+        const baserowOptions = PrismaBaserowMapper.transformPrismaToBaserow(options, fieldMetadata)
+        return (await this.rowService.search(table.id, query, baserowOptions)) as T[]
+      },
+
+      /**
+       * Obtener todas las filas sin paginación
+       *
+       * Descarga toda la tabla usando paginación automática.
+       * Útil para exportaciones o procesamiento completo.
+       *
+       * @param options - Opciones de filtrado y ordenamiento
+       * @returns Promise con todas las filas de la tabla
+       *
+       * @example
+       * ```typescript
+       * const allActiveUsers = await table.rows.findAll({
+       *   where: { status: 'active' },
+       *   orderBy: { created_at: 'asc' }
+       * })
+       * ```
+       *
+       * @since 1.2.0
+       */
+      findAll: async <T = Row>(options?: Omit<PrismaLikeQueryOptions<T>, 'take' | 'skip'>): Promise<T[]> => {
+        const table = await this.get()
+        const fieldMetadata = await this.getFieldMetadata()
+        const baserowOptions = PrismaBaserowMapper.transformPrismaToBaserow(options, fieldMetadata)
+        return (await this.rowService.listAll(table.id, baserowOptions)) as T[]
+      },
+
+      // === COMPATIBILIDAD LEGACY ===
+
+      /**
+       * Listar filas (sintaxis legacy)
+       *
+       * Método de compatibilidad para código existente.
+       * Mantiene la API original intacta.
+       *
+       * @param options - Opciones en formato legacy
+       * @returns Promise con respuesta paginada legacy
+       *
+       * @since 1.0.0
+       * @deprecated Usar findMany() para nueva funcionalidad
+       */
+      list: async (options?: QueryOptions) => {
+        const table = await this.get()
+        return await this.rowService.list(table.id, options)
+      }
+    }
+  }
+
+  /**
+   * Actualizar esta tabla
+   *
+   * Actualiza los datos de la tabla. Solo actualiza los campos
+   * proporcionados (actualización parcial). Actualiza el cache interno
+   * si el nombre cambia.
+   *
+   * @param data - Datos a actualizar
+   * @param data.name - Nuevo nombre de la tabla (opcional)
+   * @returns Promise con la tabla actualizada
+   *
+   * @throws {BaserowNotFoundError} Si la tabla no existe
+   * @throws {BaserowValidationError} Si los datos son inválidos
+   *
+   * @example
+   * ```typescript
+   * const updated = await table.update({
+   *   name: 'Nuevo Nombre Tabla'
+   * })
+   * console.log(`Tabla actualizada: ${updated.name}`)
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async update(data: Partial<CreateTableRequest>): Promise<Table> {
+    const table = await this.get()
+    const contextAccess = (this.tableService as any)[Symbol.for('tableContext')]
+    const updatedTable = await contextAccess.updateTable(table.id, data)
+
+    // Actualizar cache si el nombre cambió
+    if (data.name && data.name !== table.name) {
+      this.resolvedTable = updatedTable
+      if (this.logger) {
+        this.logger.info(`Table updated: "${data.name}" (ID: ${updatedTable.id})`)
+      }
+    }
+
+    return updatedTable
+  }
+
+  /**
+   * Eliminar esta tabla
+   *
+   * Elimina permanentemente la tabla y todos sus campos, filas y datos.
+   * Esta operación no se puede deshacer. Limpia el cache interno.
+   *
+   * @returns Promise que resuelve cuando la tabla es eliminada
+   *
+   * @throws {BaserowNotFoundError} Si la tabla no existe
+   *
+   * @example
+   * ```typescript
+   * await table.delete()
+   * console.log('Tabla eliminada exitosamente')
+   * ```
+   *
+   * @since 1.0.0
+   */
+  async delete(): Promise<void> {
+    const table = await this.get()
+    const contextAccess = (this.tableService as any)[Symbol.for('tableContext')]
+    await contextAccess.deleteTable(table.id)
+
+    if (this.logger) {
+      this.logger.info(`Table deleted: "${table.name}" (ID: ${table.id})`)
+    }
+
+    // Limpiar cache
+    this.resolvedTable = undefined
+  }
+
+  /**
+   * Obtener esta tabla completa
+   *
+   * Recupera la tabla con todos sus datos y metadatos.
+   * Utiliza lazy loading con cache para evitar resoluciones repetidas.
+   * Soporta identificación por nombre o ID de la tabla.
+   *
+   * @returns Promise con la tabla completa
+   *
+   * @throws {BaserowNotFoundError} Si la tabla no existe
+   * @throws {BaserowValidationError} Si el identificador es inválido
+   *
+   * @example Obtener por nombre
+   * ```typescript
+   * const table = await admin.workspace('WS').database('DB').table('Mi Tabla').get()
+   * console.log(`Tabla: ${table.name} (ID: ${table.id})`)
+   * console.log(`Filas: ${table.rows_count || 0}`)
+   * ```
+   *
+   * @example Obtener por ID
+   * ```typescript
+   * const table = await admin.workspace('WS').database('DB').table(123).get()
+   * console.log(`Nombre: ${table.name}`)
+   * console.log(`Database ID: ${table.database_id}`)
+   * ```
+   *
+   * @since 1.1.0
+   */
+  async get(): Promise<Table> {
+    if (this.resolvedTable) {
+      return this.resolvedTable
+    }
+
+    if (typeof this.tableIdentifier === 'number') {
+      // Es un ID numérico
+      const table = await this.tableService.get(this.tableIdentifier)
+      this.resolvedTable = table
+    } else {
+      // Es un nombre string - necesitamos resolver database primero
+      validateRequired(this.tableIdentifier, 'table name')
+
+      // Resolver database
+      let database: Database
+      if (typeof this.databaseIdentifier === 'number') {
+        const foundDatabase = await this.databaseService.findUnique(this.databaseIdentifier)
+        if (!foundDatabase) {
+          throw new BaserowNotFoundError('Database', this.databaseIdentifier)
+        }
+        database = foundDatabase
+      } else {
+        const foundDatabase = await this.databaseService.findUnique(this.databaseIdentifier)
+        if (!foundDatabase) {
+          throw new BaserowNotFoundError('Database', this.databaseIdentifier)
+        }
+        database = foundDatabase
+      }
+
+      // Buscar tabla por nombre en la database
+      const table = await this.tableService.findUnique(database.id, this.tableIdentifier)
+      if (!table) {
+        throw new BaserowNotFoundError('Table', this.tableIdentifier)
+      }
+
+      this.resolvedTable = table
+    }
+
+    if (this.logger) {
+      this.logger.info(`Retrieved table: "${this.resolvedTable.name}" (ID: ${this.resolvedTable.id})`)
+    }
+
+    return this.resolvedTable
+  }
+
+  /**
+   * Verificar si esta tabla existe
+   *
+   * Método de utilidad para verificar la existencia de la tabla
+   * sin cargar todos sus datos. Útil para validaciones previas.
+   *
+   * @returns Promise con true si existe, false si no
+   *
+   * @example Verificar existencia por nombre
+   * ```typescript
+   * const exists = await admin.workspace('WS').database('DB').table('Mi Tabla').exists()
+   * if (exists) {
+   *   console.log('La tabla existe')
+   * } else {
+   *   console.log('La tabla no fue encontrada')
+   * }
+   * ```
+   *
+   * @example Verificar antes de crear
+   * ```typescript
+   * const tableName = 'Nueva Tabla'
+   * const tableContext = admin.workspace('WS').database('DB').table(tableName)
+   * const exists = await tableContext.exists()
+   *
+   * if (!exists) {
+   *   await tableContext.create()
+   *   console.log('Tabla creada exitosamente')
+   * } else {
+   *   console.log('La tabla ya existe')
+   * }
+   * ```
+   *
+   * @since 1.1.0
+   */
+  async exists(): Promise<boolean> {
+    try {
+      await this.get()
+      return true
+    } catch (error) {
+      if ((error as any).name === 'BaserowNotFoundError') {
+        return false
+      }
+      throw error
+    }
+  }
+}