@gzl10/baserow 1.2.0

package/src/contexts/FieldContext.ts

@@ -0,0 +1,399 @@
+import { Logger, Field, BaserowNotFoundError, FieldConstraint, ConstraintType } from '../types'
+import { FieldService } from '../services/FieldService'
+import { validateRequired } from '../utils/validation'
+
+/**
+ * Context para operaciones en un campo específico
+ *
+ * Proporciona una API fluida para operaciones específicas en un campo individual
+ * identificado por nombre o ID. Permite operaciones contextuales como update, delete
+ * y gestión avanzada de índices y restricciones con API intuitiva.
+ *
+ * **Características principales:**
+ * - Resolución automática de campo por nombre o ID (lazy loading)
+ * - API intuitiva para operaciones avanzadas: index(), constraint()
+ * - Operaciones CRUD específicas: update(), delete()
+ * - Cache interno para evitar resoluciones repetidas
+ * - Logging opcional de todas las operaciones
+ * - Validación automática de parámetros
+ *
+ * **Patrón de API Contextual:**
+ * ```
+ * field('nombre').update(data)           // Actualizar campo específico
+ * field('nombre').delete()               // Eliminar campo específico
+ * field('email').index(true)             // Habilitar índice
+ * field('codigo').constraint({ type: 'unique', active: true })  // Agregar restricción
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Operaciones CRUD específicas
+ * await table.field('nombre').update({ description: 'Nombre completo' })
+ * await table.field('obsoleto').delete()
+ *
+ * // Gestión de índices (v1.35+)
+ * await table.field('email').index(true)   // Habilitar índice
+ * await table.field('email').index(false)  // Deshabilitar índice
+ *
+ * // Gestión de restricciones (v1.35+)
+ * await table.field('email').constraint({ type: 'unique', active: true })  // Agregar
+ * await table.field('email').constraint('unique')                          // Eliminar
+ * const constraints = await table.field('codigo').getConstraints()
+ *
+ * // Funciona con ID también
+ * await table.field(123).update({ name: 'Nuevo Nombre' })
+ * await table.field(456).index(true)
+ * ```
+ *
+ * @since 1.1.0
+ */
+export class FieldContext {
+  private fieldIdentifier: string | number
+  private resolvedField?: Field
+  private logger?: Logger
+
+  /**
+   * Crea un nuevo context de campo
+   *
+   * @param fieldService - Servicio para operaciones de campos
+   * @param getTableId - Función para obtener el ID de la tabla padre
+   * @param fieldIdentifier - Nombre o ID del campo
+   * @param logger - Logger opcional para debug y trazabilidad
+   *
+   * @since 1.1.0
+   */
+  constructor(
+    private fieldService: FieldService,
+    private getTableId: () => Promise<number>,
+    fieldIdentifier: string | number,
+    logger?: Logger
+  ) {
+    this.fieldIdentifier = fieldIdentifier
+    this.logger = logger
+  }
+
+  /**
+   * Actualizar este campo
+   *
+   * Actualiza los datos del campo. 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 del campo (opcional)
+   * @param data.description - Nueva descripción (opcional)
+   * @returns Promise con el campo actualizado
+   *
+   * @throws {BaserowNotFoundError} Si el campo no existe
+   * @throws {BaserowValidationError} Si los datos son inválidos
+   *
+   * @example
+   * ```typescript
+   * const updated = await table.field('email').update({
+   *   name: 'Email Corporativo',
+   *   description: 'Email principal de contacto'
+   * })
+   * console.log(`Campo actualizado: ${updated.name}`)
+   * ```
+   *
+   * @since 1.1.0
+   */
+  async update(data: any): Promise<Field> {
+    const field = await this.get()
+    const contextAccess = (this.fieldService as any)[Symbol.for('fieldContext')]
+    const updatedField = await contextAccess.updateField(field.id, data)
+
+    // Actualizar cache si el nombre cambió
+    if (data.name && data.name !== field.name) {
+      this.resolvedField = updatedField
+      if (this.logger) {
+        this.logger.info(`Field updated: "${data.name}" (ID: ${updatedField.id})`)
+      }
+    }
+
+    return updatedField
+  }
+
+  /**
+   * Eliminar este campo
+   *
+   * Elimina permanentemente el campo y todos sus datos.
+   * Esta operación no se puede deshacer. Limpia el cache interno.
+   *
+   * @returns Promise que resuelve cuando el campo es eliminado
+   *
+   * @throws {BaserowNotFoundError} Si el campo no existe
+   *
+   * @example
+   * ```typescript
+   * await table.field('campo_obsoleto').delete()
+   * console.log('Campo eliminado exitosamente')
+   * ```
+   *
+   * @since 1.1.0
+   */
+  async delete(): Promise<void> {
+    const field = await this.get()
+    const contextAccess = (this.fieldService as any)[Symbol.for('fieldContext')]
+    await contextAccess.deleteField(field.id)
+
+    if (this.logger) {
+      this.logger.info(`Field deleted: "${field.name}" (ID: ${field.id})`)
+    }
+
+    // Limpiar cache
+    this.resolvedField = undefined
+  }
+
+  /**
+   * Configurar índice en este campo
+   *
+   * Habilita o deshabilita el índice en el campo para mejorar performance
+   * de filtros y búsquedas. API más intuitiva que setFieldIndex().
+   *
+   * @param enabled - true para habilitar índice, false para deshabilitar
+   * @returns Promise con el campo actualizado
+   *
+   * @example
+   * ```typescript
+   * // Habilitar índice para mejor performance en filtros
+   * await table.field('email').index(true)
+   *
+   * // Deshabilitar índice
+   * await table.field('email').index(false)
+   * ```
+   *
+   * @since 1.1.0
+   */
+  async index(enabled: boolean): Promise<Field> {
+    const field = await this.get()
+    const updatedField = await this.fieldService.setFieldIndex(field.id, enabled)
+
+    // Actualizar cache
+    this.resolvedField = updatedField
+
+    if (this.logger) {
+      this.logger.info(`Field index ${enabled ? 'enabled' : 'disabled'}: "${field.name}" (ID: ${field.id})`)
+    }
+
+    return updatedField
+  }
+
+  /**
+   * Gestionar restricción de valor en este campo
+   *
+   * API unificada para agregar o eliminar restricciones de valor.
+   * Sobrecarga de función para APIs intuitivas:
+   * - constraint(object) = agregar restricción
+   * - constraint(string) = eliminar restricción por tipo
+   *
+   * @param constraintOrType - Objeto de restricción para agregar, o string del tipo para eliminar
+   * @returns Promise con el campo actualizado
+   *
+   * @example
+   * ```typescript
+   * // Agregar restricción unique
+   * await table.field('email').constraint({ type: 'unique', active: true })
+   *
+   * // Agregar restricción unique_with_empty
+   * await table.field('codigo').constraint({ type: 'unique_with_empty', active: true })
+   *
+   * // Eliminar restricción por tipo
+   * await table.field('email').constraint('unique')
+   * await table.field('codigo').constraint('unique_with_empty')
+   * ```
+   *
+   * @since 1.1.0
+   */
+  async constraint(constraintOrType: FieldConstraint | ConstraintType): Promise<Field> {
+    const field = await this.get()
+
+    let updatedField: Field
+
+    if (typeof constraintOrType === 'string') {
+      // Eliminar restricción por tipo
+      updatedField = await this.fieldService.removeFieldConstraint(field.id, constraintOrType)
+
+      if (this.logger) {
+        this.logger.info(`Field constraint removed: "${constraintOrType}" from "${field.name}" (ID: ${field.id})`)
+      }
+    } else {
+      // Agregar restricción
+      updatedField = await this.fieldService.addFieldConstraint(field.id, constraintOrType)
+
+      if (this.logger) {
+        this.logger.info(`Field constraint added: "${constraintOrType.type}" to "${field.name}" (ID: ${field.id})`)
+      }
+    }
+
+    // Actualizar cache
+    this.resolvedField = updatedField
+
+    return updatedField
+  }
+
+  /**
+   * Obtener todas las restricciones de este campo
+   *
+   * @returns Promise con array de restricciones activas en el campo
+   *
+   * @example
+   * ```typescript
+   * const constraints = await table.field('email').getConstraints()
+   * constraints.forEach(constraint => {
+   *   console.log(`${constraint.type}: ${constraint.active ? 'activa' : 'inactiva'}`)
+   * })
+   * ```
+   *
+   * @since 1.1.0
+   */
+  async getConstraints(): Promise<FieldConstraint[]> {
+    const field = await this.get()
+    return await this.fieldService.getFieldConstraints(field.id)
+  }
+
+  /**
+   * Eliminar todas las restricciones del campo
+   *
+   * Remueve completamente todas las constraints configuradas en este campo,
+   * dejándolo sin ninguna restricción de integridad. Esta operación es útil
+   * para limpiar campos que han acumulado múltiples constraints o para resetear
+   * completamente la configuración de restricciones.
+   *
+   * @returns Promise con el campo actualizado sin constraints
+   *
+   * @throws {BaserowNotFoundError} Si el campo no existe
+   * @throws {BaserowError} Si hay error en la comunicación con la API
+   *
+   * @example
+   * ```typescript
+   * // Eliminar todas las constraints de un campo
+   * const field = await table.field('email').deleteConstraints()
+   * console.log(`Campo "${field.name}" ahora sin constraints`)
+   *
+   * // Verificar que se eliminaron todas
+   * const constraints = await table.field('email').getConstraints()
+   * console.log(`Constraints restantes: ${constraints.length}`) // 0
+   * ```
+   *
+   * @since 1.1.0
+   */
+  async deleteConstraints(): Promise<Field> {
+    const field = await this.get()
+    const updatedField = await this.fieldService.removeAllFieldConstraints(field.id)
+
+    if (this.logger) {
+      this.logger.info(`All constraints removed from field "${field.name}" (ID: ${field.id})`)
+    }
+
+    // Actualizar cache
+    this.resolvedField = updatedField
+
+    return updatedField
+  }
+
+  /**
+   * Obtener este campo completo
+   *
+   * Recupera el campo con todos sus datos y metadatos.
+   * Utiliza lazy loading con cache para evitar resoluciones repetidas.
+   * Soporta identificación por nombre o ID del campo.
+   *
+   * @returns Promise con el campo completo
+   *
+   * @throws {BaserowNotFoundError} Si el campo no existe
+   * @throws {BaserowValidationError} Si el identificador es inválido
+   *
+   * @example Obtener por nombre
+   * ```typescript
+   * const field = await table.field('email').get()
+   * console.log(`Campo: ${field.name} (ID: ${field.id})`)
+   * console.log(`Tipo: ${field.type}`)
+   * ```
+   *
+   * @example Obtener por ID
+   * ```typescript
+   * const field = await table.field(123).get()
+   * console.log(`Nombre: ${field.name}`)
+   * console.log(`Descripción: ${field.description || 'Sin descripción'}`)
+   * ```
+   *
+   * @since 1.1.0
+   */
+  async get(): Promise<Field> {
+    if (this.resolvedField) {
+      return this.resolvedField
+    }
+
+    if (typeof this.fieldIdentifier === 'number') {
+      // Es un ID numérico
+      const field = await this.fieldService.get(this.fieldIdentifier)
+      this.resolvedField = field
+    } else {
+      // Es un nombre string - necesitamos buscar en la tabla
+      validateRequired(this.fieldIdentifier, 'field name')
+
+      // Obtener tableId desde TableContext
+      const tableId = await this.getTableId()
+
+      // Buscar campo por nombre en la tabla
+      const field = await this.fieldService.findUnique(tableId, this.fieldIdentifier)
+      if (!field) {
+        throw new BaserowNotFoundError('Field', this.fieldIdentifier)
+      }
+
+      this.resolvedField = field
+    }
+
+    if (this.logger) {
+      this.logger.info(`Retrieved field: "${this.resolvedField.name}" (ID: ${this.resolvedField.id})`)
+    }
+
+    return this.resolvedField
+  }
+
+  /**
+   * Verificar si este campo existe
+   *
+   * Método de utilidad para verificar la existencia del campo
+   * 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 table.field('email').exists()
+   * if (exists) {
+   *   console.log('El campo existe')
+   * } else {
+   *   console.log('El campo no fue encontrado')
+   * }
+   * ```
+   *
+   * @example Verificar antes de crear
+   * ```typescript
+   * const fieldName = 'nuevo_campo'
+   * const exists = await table.field(fieldName).exists()
+   *
+   * if (!exists) {
+   *   await table.fields.createText(fieldName, undefined, 'Campo creado dinámicamente')
+   *   console.log('Campo creado exitosamente')
+   * } else {
+   *   console.log('El campo 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
+    }
+  }
+}

package/src/contexts/RowContext.ts

@@ -0,0 +1,99 @@
+import { Logger, Row } from '../types'
+import { RowService } from '../services/RowService'
+
+/**
+ * Context para operaciones en una fila específica con TableOnlyContext
+ * Proporciona API simplificada para operaciones CRUD de una sola fila
+ */
+export class RowOnlyContext {
+  constructor(
+    private tableId: number | (() => Promise<number>),
+    private rowId: number,
+    private rowService: RowService,
+    private logger?: Logger
+  ) {}
+
+  private async getTableId(): Promise<number> {
+    if (typeof this.tableId === 'function') {
+      return await this.tableId()
+    }
+    return this.tableId
+  }
+
+  /**
+   * Obtener los datos de la fila
+   *
+   * @returns Promise con los datos de la fila
+   *
+   * @example
+   * ```typescript
+   * const rowData = await client.table(123).row(456).get()
+   * console.log(rowData.name)
+   * ```
+   */
+  async get(): Promise<Row> {
+    const tableId = await this.getTableId()
+    this.logger?.info(`[RowOnlyContext] Getting row ${this.rowId} from table ${tableId}`)
+    return await this.rowService.get(tableId, this.rowId, true)
+  }
+
+  /**
+   * Actualizar los datos de la fila
+   *
+   * @param data - Datos parciales para actualizar
+   * @returns Promise con los datos actualizados de la fila
+   *
+   * @example
+   * ```typescript
+   * const updated = await client.table(123).row(456).update({
+   *   name: 'Nuevo nombre',
+   *   active: false
+   * })
+   * ```
+   */
+  async update(data: Partial<Row>): Promise<Row> {
+    const tableId = await this.getTableId()
+    this.logger?.info(`[RowOnlyContext] Updating row ${this.rowId} in table ${tableId}`)
+    return await this.rowService.updateRow(tableId, this.rowId, data)
+  }
+
+  /**
+   * Eliminar la fila
+   *
+   * @returns Promise que se resuelve cuando la fila es eliminada
+   *
+   * @example
+   * ```typescript
+   * await client.table(123).row(456).delete()
+   * console.log('Fila eliminada')
+   * ```
+   */
+  async delete(): Promise<void> {
+    const tableId = await this.getTableId()
+    this.logger?.info(`[RowOnlyContext] Deleting row ${this.rowId} from table ${tableId}`)
+    await this.rowService.delete(tableId, this.rowId)
+  }
+
+  /**
+   * Verificar si la fila existe
+   *
+   * @returns Promise con true si existe, false si no
+   *
+   * @example
+   * ```typescript
+   * const exists = await client.table(123).row(456).exists()
+   * if (exists) {
+   *   console.log('La fila existe')
+   * }
+   * ```
+   */
+  async exists(): Promise<boolean> {
+    try {
+      const tableId = await this.getTableId()
+      await this.rowService.get(tableId, this.rowId)
+      return true
+    } catch {
+      return false
+    }
+  }
+}