Skip to main content

AlpuraOfflineUtil – Guía de uso

Este documento explica cómo usar la utilidad AlpuraOfflineUtil de la librería de @alpura/core, la cual provee un operador de RxJS para gestionar peticiones HTTP en modo offline.

📁 Importaciones necesarias​

En tu servicio, importa AlpuraOfflineUtil desde la librería de @alpura/core.

import { AlpuraOfflineUtil } from "@alpura/core";

🧩 Método Disponible: syncWhenOffline​

La utilidad expone un método estático syncWhenOffline que funciona como un operador de RxJS. Su propósito es interceptar una petición HTTP y guardarla localmente si no hay conexión a internet.

Firma​

AlpuraOfflineUtil.syncWhenOffline<T>(isOnline: boolean, requestData: object)
  • isOnline: Un booleano que indica el estado actual de la conexión.
  • requestData: Un objeto con los detalles de la petición a guardar (método, URL, cuerpo, etc.).

Comportamiento​

  • Si isOnline es true: El operador no hace nada y deja que la petición HTTP continúe hacia el servidor.
  • Si isOnline es false: El operador intercepta la llamada, la guarda en la base de datos local (usando AlpuraPouchDbUtil) y devuelve un Observable con una respuesta mock que notifica al suscriptor que la operación fue guardada.

🧩 Método Disponible: syncCacheCatalog​

Esta utilidad también ofrece un operador de RxJS llamado syncCacheCatalog. Su función es cachear respuestas de peticiones HTTP (generalmente catálogos o datos que no cambian a menudo) para poder consultarlas cuando no hay conexión a internet.

Firma​

AlpuraOfflineUtil.syncCacheCatalog<T>(isOnline: boolean, requestData: IRequestCatalogOffline)
  • pouchDbKey: Un string que funciona como identificador único para guardar y recuperar el catálogo en la base de datos local.
  • isOnline: Un booleano que indica el estado de la conexión.
  • size: (Opcional) Número de elementos a devolver en la paginación.
  • offset: (Opcional) Desplazamiento o página inicial para la paginación.
  • requestData: Un objeto con los detalles de la petición (solo el parametro url del requestData es obligatorio)

Comportamiento​

  • Si isOnline es true: El operador deja que la petición HTTP se complete. Cuando recibe una respuesta exitosa, la guarda (o actualiza) en la base de datos local usando la pouchDbKey proporcionada.
  • Si isOnline es false: El operador intercepta la llamada y busca en la base de datos local un catálogo que coincida con la pouchDbKey.
    • Si lo encuentra: Devuelve un Observable con los datos cacheados.
    • Si no lo encuentra: Devuelve un Observable con un error, notificando que no hay conexión ni datos en caché.

🧩 Ejemplos de uso​

Para peticiones de escritura (POST, PUT, DELETE)​

El operador syncWhenOffline se debe colocar dentro del .pipe() de una llamada HttpClient, típicamente en métodos que modifican datos.

import { HttpClient } from '@angular/common/http';
import { Injectable, inject } from '@angular/core';
import { AlpuraOfflineUtil } from '@alpura/core';
import { AlpuraStorageViewModel } from '@alpura/commons';
import { Observable } from 'rxjs';

@Injectable({ providedIn: 'root' })
export class DataService {
  private http = inject(HttpClient);
  private readonly storage = inject(AlpuraStorageViewModel);

  createItem(itemPayload: any): Observable<any> {
    const url = 'https://api.example.com/items';
    // obtiene el estado de conexión
    const isOnline = this.storage.getStorageMap('IS_ONLINE') as boolean;

    return this.http.post(url, itemPayload).pipe(
      AlpuraOfflineUtil.syncWhenOffline(isOnline, {
        method: 'POST',
        url,
        body: itemPayload,
      })
    );
  }
}

Para cacheo de catálogos (GET)​

El operador syncCacheCatalog se utiliza en el .pipe() de llamadas HttpClient que obtienen datos que pueden ser cacheados.

import { HttpClient } from '@angular/common/http';
import { Injectable, inject } from '@angular/core';
import { AlpuraOfflineUtil } from '@alpura/core';
import { AlpuraStorageViewModel } from '@alpura/commons';
import { Observable } from 'rxjs';

@Injectable({ providedIn: 'root' })
export class CatalogService {
  private http = inject(HttpClient);
  private readonly storage = inject(AlpuraStorageViewModel);

  getRoles(): Observable<any[]> {
    const url = 'https://api.example.com/roles';
    const POUCH_DB_KEY = 'catalog_roles';
    // obtiene el estado de conexión
    const isOnline = this.storage.getStorageMap('IS_ONLINE') as boolean;

    return this.http.get<any[]>(url).pipe(
      AlpuraOfflineUtil.syncCacheCatalog(POUCH_DB_KEY, isOnline)
    );
  }
}

🚀 Resultado esperado​

La utilidad AlpuraOfflineUtil centraliza la lógica para gestionar peticiones HTTP cuando la aplicación está offline. Al usarla en el pipe de RxJS, se asegura que:

  1. Las operaciones de escritura (POST, PUT, DELETE) no se pierdan y queden en una cola para ser sincronizadas cuando la conexión se restablezca (syncWhenOffline).
  2. Los datos de solo lectura (GET), como catálogos, puedan ser cacheados y consultados sin conexión (syncCacheCatalog).

Esto proporciona una experiencia de usuario más fluida y robusta frente a problemas de conectividad.

📬 Soporte​

Para dudas o mejoras, puedes contactar al equipo de arquitectura.