Skip to main content

Batching

Optimize performance by saving form changes in batches instead of on every keystroke.

Overview​

Batching allows you to:

  • Reduce IndexedDB write operations
  • Improve performance for forms with many fields
  • Control save frequency based on your needs
  • Balance between data safety and performance

How It Works​

When batching is enabled:

  1. First change - Saves immediately (for quick feedback)
  2. Subsequent changes - Accumulated and saved in batches
  3. Batch interval - Configurable delay between batch saves

Basic Usage​

With useFormAutosave​

import { useFormAutosave } from '@form-guardian/react';

function MyForm() {
  const { formRef } = useFormAutosave('my-form', {
    // Save changes in batches every 5 seconds
    batchSaveInterval: 5000, // milliseconds
  });

  return <form ref={formRef}>...</form>;
}

With attachFormAutosave​

import { attachFormAutosave } from '@form-guardian/dom';

const autosave = attachFormAutosave({
  formId: 'my-form',
  root: formElement,
  // Save changes in batches every 3 seconds
  batchSaveInterval: 3000,
});

Behavior​

Without Batching (Default)​

// Every keystroke triggers a save (after debounce)
const { formRef } = useFormAutosave('my-form', {
  debounceMs: 500, // Wait 500ms after user stops typing
  // batchSaveInterval: undefined (disabled)
});

Timeline:

  • User types "H" → Wait 500ms → Save
  • User types "e" → Wait 500ms → Save
  • User types "l" → Wait 500ms → Save
  • User types "l" → Wait 500ms → Save
  • User types "o" → Wait 500ms → Save

Result: 5 save operations

With Batching​

const { formRef } = useFormAutosave('my-form', {
  debounceMs: 500,
  batchSaveInterval: 5000, // 5 seconds
});

Timeline:

  • User types "H" → Wait 500ms → Save immediately (first change)
  • User types "e" → Accumulate (wait for batch)
  • User types "l" → Accumulate
  • User types "l" → Accumulate
  • User types "o" → Accumulate
  • After 5 seconds → Save batch (all accumulated changes)

Result: 2 save operations (1 immediate + 1 batch)

Configuration​

Disable Batching​

// Batching is disabled by default
const { formRef } = useFormAutosave('my-form', {
  // batchSaveInterval: undefined (disabled)
});

// Or explicitly disable
const { formRef } = useFormAutosave('my-form', {
  batchSaveInterval: 0, // Disabled
});

Short Intervals (Frequent Saves)​

// Save every 1 second (more frequent, less performance gain)
const { formRef } = useFormAutosave('my-form', {
  batchSaveInterval: 1000,
});

Use case: Forms where data loss is critical, but you still want some batching.

Long Intervals (Less Frequent Saves)​

// Save every 30 seconds (better performance, higher risk of data loss)
const { formRef } = useFormAutosave('my-form', {
  batchSaveInterval: 30000,
});

Use case: Forms with many fields where performance is more important than immediate saves.

Best Practices​

1. Balance Performance and Data Safety​

// Good: Moderate interval for most forms
const { formRef } = useFormAutosave('contact-form', {
  batchSaveInterval: 5000, // 5 seconds
});

// Good: Shorter interval for critical forms
const { formRef } = useFormAutosave('payment-form', {
  batchSaveInterval: 2000, // 2 seconds
});

// Good: Longer interval for large forms
const { formRef } = useFormAutosave('large-form', {
  batchSaveInterval: 10000, // 10 seconds
});

2. Combine with Debounce​

// Debounce prevents saves on every keystroke
// Batching groups multiple changes together
const { formRef } = useFormAutosave('my-form', {
  debounceMs: 500,        // Wait 500ms after typing stops
  batchSaveInterval: 5000, // Then batch every 5 seconds
});

3. Handle Page Unload​

Batching automatically saves pending changes when:

  • Form is destroyed
  • Page is unloaded (if possible)
  • Draft is manually cleared
const { formRef, clearDraft } = useFormAutosave('my-form', {
  batchSaveInterval: 5000,
});

// On form submit, clear will save any pending changes first
const onSubmit = async () => {
  await clearDraft(); // Pending changes are saved before clearing
};

Performance Impact​

Without Batching​

For a form with 20 fields, user makes 50 changes:

  • Save operations: ~50 (one per change after debounce)
  • IndexedDB writes: ~50
  • Performance: Slower, especially on low-end devices

With Batching (5 second interval)​

For the same form:

  • Save operations: ~10 (first change + batches)
  • IndexedDB writes: ~10
  • Performance: 5x fewer writes, significantly faster

Real-World Example​

import { useFormAutosave } from '@form-guardian/react';

function LargeForm() {
  const { formRef } = useFormAutosave('large-form', {
    // Debounce: Wait 500ms after user stops typing
    debounceMs: 500,
    // Batching: Save accumulated changes every 5 seconds
    batchSaveInterval: 5000,
    // Analytics: Track batch saves
    onAfterSave: async (values) => {
      console.log('Batch saved:', Object.keys(values).length, 'fields');
    },
  });

  return (
    <form ref={formRef}>
      {/* 50+ form fields */}
    </form>
  );
}

When to Use Batching​

✅ Use Batching When:​

  • Form has many fields (20+)
  • Users make rapid changes
  • Performance is a concern
  • IndexedDB writes are slow
  • You can tolerate slight delay in saves

❌ Don't Use Batching When:​

  • Form has few fields (< 5)
  • Data loss is critical (payment forms)
  • You need immediate saves
  • Form is rarely used

Next Steps​