@craftthingy-digital-innovation/cty-offline-outbox-sync-web

Bilingual documentation: Bahasa Indonesia | English

Bahasa Indonesia

Library client-side Javascript untuk menangani pengiriman data otomatis (auto-save) dengan kemampuan penyimpanan lokal sementara (localStorage outbox) dan pencobaan ulang otomatis (auto-retry) berkala jika koneksi terputus.

Sangat berguna untuk aplikasi web yang membutuhkan persistensi tinggi (seperti spreadsheet, form panjang, CRM) agar terhindar dari kehilangan data saat jaringan buruk.

Instalasi

npm install @craftthingy-digital-innovation/cty-offline-outbox-sync-web

Cara Penggunaan

import { OfflineOutbox } from '@craftthingy-digital-innovation/cty-offline-outbox-sync-web';

const outbox = new OfflineOutbox({
  storageKey: 'paspor_offline_queue', // Kunci localStorage
  retryInterval: 6000, // Waktu tunggu coba kembali (6 detik)
  onSync: async (item) => {
    // Jalankan pengiriman data asinkron Anda ke server
    const response = await fetch('/api/save', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(item.postData)
    });
    return await response.json();
  }
});

// Masukkan perubahan data ke outbox (akan di-merge otomatis jika UUID sama)
outbox.enqueue('row-uuid-123', { nama_pemohon: 'Alif Nurhidayat' });

// Dengarkan perubahan status sinkronisasi untuk update UI badge
outbox.on('status-change', ({ pendingCount, online }) => {
  if (!online) {
    updateStatusUI(`Koneksi terputus. Menyimpan lokal... (${pendingCount} tertunda)`);
  } else if (pendingCount > 0) {
    updateStatusUI(`Menyinkronkan... (${pendingCount} perubahan)`);
  } else {
    updateStatusUI('Semua data tersimpan otomatis');
  }
});

English

A client-side JavaScript library to handle automatic form submissions (auto-save) with local cache fallback (localStorage outbox) and periodic auto-retry capabilities when connections are disrupted.

Extremely useful for sheets, databases, long forms, or CRMs to prevent data loss on unstable networks.

Installation

npm install @craftthingy-digital-innovation/cty-offline-outbox-sync-web

Usage

import { OfflineOutbox } from '@craftthingy-digital-innovation/cty-offline-outbox-sync-web';

const outbox = new OfflineOutbox({
  storageKey: 'paspor_offline_queue', // Key in localStorage
  retryInterval: 6000, // Retry interval (6 seconds)
  onSync: async (item) => {
    // Execute your async API save request
    const response = await fetch('/api/save', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(item.postData)
    });
    return await response.json();
  }
});

// Enqueue changes (automatically merged if same UUID is modified)
outbox.enqueue('row-uuid-123', { nama_pemohon: 'Alif Nurhidayat' });

// Listen for status changes to update your UI indicators
outbox.on('status-change', ({ pendingCount, online }) => {
  if (!online) {
    updateStatusUI(`Connection offline. Saved locally (${pendingCount} pending)`);
  } else if (pendingCount > 0) {
    updateStatusUI(`Syncing... (${pendingCount} changes)`);
  } else {
    updateStatusUI('All data saved automatically');
  }
});