@gzl10/baserow 1.2.0

package/src/presets/performance.ts

@@ -0,0 +1,262 @@
+import type { BaserowPerformanceOptions } from '../types'
+
+/**
+ * Colección de configuraciones de performance predefinidas para diferentes entornos y casos de uso
+ *
+ * Facilita la selección de configuraciones apropiadas sin tener que conocer los valores específicos.
+ * Cada preset está optimizado para escenarios específicos de uso.
+ *
+ * @example Uso básico con presets
+ * ```typescript
+ * import { BaserowClient, PERFORMANCE_PRESETS } from '@gzl10/baserow'
+ *
+ * // Para producción (balanceado)
+ * const prodClient = await BaserowClient.create({
+ *   url: 'https://baserow.example.com',
+ *   token: process.env.TOKEN,
+ *   performance: PERFORMANCE_PRESETS.production
+ * })
+ *
+ * // Para desarrollo local (más relajado)
+ * const devClient = await BaserowClient.create({
+ *   url: 'http://localhost:3000',
+ *   credentials: { email: 'dev@example.com', password: 'password' },
+ *   performance: PERFORMANCE_PRESETS.development
+ * })
+ *
+ * // Para tests (conservador)
+ * const testClient = await BaserowClient.create({
+ *   url: 'https://test.baserow.com',
+ *   token: process.env.TEST_TOKEN,
+ *   performance: PERFORMANCE_PRESETS.testing
+ * })
+ * ```
+ *
+ * @example Selección dinámica de presets
+ * ```typescript
+ * import { getPerformancePreset } from '@gzl10/baserow'
+ *
+ * const envToPreset = {
+ *   production: 'production',
+ *   staging: 'testing',
+ *   development: 'development'
+ * } as const
+ *
+ * const preset = getPerformancePreset(envToPreset[process.env.NODE_ENV as keyof typeof envToPreset])
+ * ```
+ *
+ * @since 1.1.0
+ * @public
+ */
+export const PERFORMANCE_PRESETS = {
+  /**
+   * Configuración balanceada para entornos de producción
+   *
+   * Optimizada para un equilibrio entre performance y estabilidad en producción.
+   * Valores probados para cargas de trabajo estándar.
+   *
+   * @example
+   * ```typescript
+   * const client = await BaserowClient.create({
+   *   url: 'https://api.baserow.com',
+   *   token: process.env.BASEROW_TOKEN,
+   *   performance: PERFORMANCE_PRESETS.production
+   * })
+   * ```
+   *
+   * - **Timeout**: 30 segundos (estándar para APIs REST)
+   * - **Reintentos**: 3 (recuperación robusta de errores temporales)
+   * - **Rate limiting**: 10 req/s (equilibrio entre throughput y respeto al servidor)
+   * - **Casos de uso**: APIs en producción, integraciones estables, servicios críticos
+   *
+   * @since 1.1.0
+   */
+  production: {
+    timeout: 30000,
+    retries: 3,
+    maxRequestsPerSecond: 10,
+    enableRateLimiting: true
+  } as BaserowPerformanceOptions,
+
+  /**
+   * Configuración relajada para desarrollo local
+   *
+   * Diseñada para desarrollo cómodo con tiempos más generosos para debugging.
+   * Menos agresiva para facilitar el desarrollo y troubleshooting.
+   *
+   * @example
+   * ```typescript
+   * const devClient = await BaserowClient.create({
+   *   url: 'http://localhost:3000',
+   *   credentials: { email: 'dev@example.com', password: 'dev123' },
+   *   performance: PERFORMANCE_PRESETS.development
+   * })
+   * ```
+   *
+   * - **Timeout**: 60 segundos (tiempo adicional para debugging y breakpoints)
+   * - **Reintentos**: 2 (menos agresivo durante desarrollo)
+   * - **Rate limiting**: 5 req/s (conservador para instancias locales)
+   * - **Casos de uso**: Desarrollo local, debugging, instancias de desarrollo
+   *
+   * @since 1.1.0
+   */
+  development: {
+    timeout: 60000,
+    retries: 2,
+    maxRequestsPerSecond: 5,
+    enableRateLimiting: true
+  } as BaserowPerformanceOptions,
+
+  /**
+   * Configuración conservadora para tests automatizados
+   *
+   * Optimizada para estabilidad en entornos de testing, especialmente CI/CD.
+   * Balanceada para ser respetuosa con recursos compartidos.
+   *
+   * @example
+   * ```typescript
+   * const testClient = await BaserowClient.create({
+   *   url: 'https://test.baserow.com',
+   *   token: process.env.BASEROW_TEST_TOKEN,
+   *   performance: PERFORMANCE_PRESETS.testing
+   * })
+   * ```
+   *
+   * - **Timeout**: 45 segundos (tiempo adicional para CI/CD lentos)
+   * - **Reintentos**: 2 (equilibrio entre estabilidad y velocidad de tests)
+   * - **Rate limiting**: 5 req/s (respetuoso con servidores de testing compartidos)
+   * - **Casos de uso**: Tests automatizados, CI/CD, entornos de QA
+   *
+   * @since 1.1.0
+   */
+  testing: {
+    timeout: 45000,
+    retries: 2,
+    maxRequestsPerSecond: 5,
+    enableRateLimiting: true
+  } as BaserowPerformanceOptions,
+
+  /**
+   * Configuración de alta performance para servicios robustos
+   *
+   * Configuración agresiva diseñada para máximo throughput en infraestructura robusta.
+   * Requiere servidores Baserow dedicados con recursos suficientes.
+   *
+   * @example
+   * ```typescript
+   * const fastClient = await BaserowClient.create({
+   *   url: 'https://dedicated.baserow.com',
+   *   token: process.env.BASEROW_FAST_TOKEN,
+   *   performance: PERFORMANCE_PRESETS.aggressive
+   * })
+   * ```
+   *
+   * - **Timeout**: 15 segundos (respuesta rápida esperada)
+   * - **Reintentos**: 5 (agresivo en recuperación de errores)
+   * - **Rate limiting**: 20 req/s (alta throughput)
+   * - **Casos de uso**: Servicios de alta demanda, servidores dedicados, APIs críticas
+   *
+   * @warning Solo usar con servidores Baserow dedicados y robustos
+   * @since 1.1.0
+   */
+  aggressive: {
+    timeout: 15000,
+    retries: 5,
+    maxRequestsPerSecond: 20,
+    enableRateLimiting: true
+  } as BaserowPerformanceOptions,
+
+  /**
+   * Configuración muy conservadora para recursos limitados
+   *
+   * Configuración minimalista diseñada para minimizar la carga en servidores con recursos limitados.
+   * Maximiza la compatibilidad y estabilidad en entornos restrictivos.
+   *
+   * @example
+   * ```typescript
+   * const conservativeClient = await BaserowClient.create({
+   *   url: 'https://shared.baserow.com',
+   *   token: process.env.BASEROW_LIMITED_TOKEN,
+   *   performance: PERFORMANCE_PRESETS.conservative
+   * })
+   * ```
+   *
+   * - **Timeout**: 60 segundos (paciencia con servidores lentos)
+   * - **Reintentos**: 1 (mínimo impacto en servidor sobrecargado)
+   * - **Rate limiting**: 2 req/s (muy respetuoso con recursos)
+   * - **Casos de uso**: Servidores compartidos, recursos limitados, procesos batch
+   *
+   * @example Casos de uso ideales
+   * ```typescript
+   * // Para servidores Baserow compartidos con muchos usuarios
+   * // Para instancias con recursos limitados (RAM/CPU)
+   * // Para procesos batch que pueden esperar
+   * // Para entornos con restricciones de red
+   * ```
+   *
+   * @since 1.1.0
+   */
+  conservative: {
+    timeout: 60000,
+    retries: 1,
+    maxRequestsPerSecond: 2,
+    enableRateLimiting: true
+  } as BaserowPerformanceOptions
+} as const
+
+/**
+ * Tipo que representa las claves disponibles en PERFORMANCE_PRESETS
+ *
+ * Útil para crear funciones que acepten solo presets válidos con autocompletado TypeScript.
+ *
+ * @example
+ * ```typescript
+ * function createClientWithPreset(preset: PerformancePresetKey) {
+ *   return BaserowClient.create({
+ *     url: 'https://baserow.example.com',
+ *     token: process.env.TOKEN,
+ *     performance: PERFORMANCE_PRESETS[preset]
+ *   })
+ * }
+ * ```
+ *
+ * @since 1.1.0
+ * @public
+ */
+export type PerformancePresetKey = keyof typeof PERFORMANCE_PRESETS
+
+/**
+ * Función helper para obtener un preset por clave con validación TypeScript
+ *
+ * Proporciona una forma programática de acceder a presets con validación de tipos.
+ * Especialmente útil cuando la selección de preset es dinámica.
+ *
+ * @param preset - Clave del preset deseado (con autocompletado)
+ * @returns Configuración de performance del preset seleccionado
+ *
+ * @example Uso básico
+ * ```typescript
+ * const config = getPerformancePreset('testing')
+ * // Equivalente a: PERFORMANCE_PRESETS.testing
+ * ```
+ *
+ * @example Selección dinámica basada en entorno
+ * ```typescript
+ * const envToPreset: Record<string, PerformancePresetKey> = {
+ *   production: 'production',
+ *   staging: 'testing',
+ *   development: 'development',
+ *   test: 'testing'
+ * }
+ *
+ * const currentPreset = getPerformancePreset(
+ *   envToPreset[process.env.NODE_ENV || 'development']
+ * )
+ * ```
+ *
+ * @since 1.1.0
+ * @public
+ */
+export function getPerformancePreset(preset: PerformancePresetKey): BaserowPerformanceOptions {
+  return PERFORMANCE_PRESETS[preset]
+}