@form-guardian/core

Headless core library for form autosave functionality. Provides IndexedDB storage, draft management, and TTL support. Framework-agnostic and works with any JavaScript environment.

Overview

@form-guardian/core is the foundation of Form Guardian. It provides low-level APIs for saving, loading, and managing form drafts using IndexedDB. This package has no framework dependencies and can be used in any JavaScript environment (browser, Node.js with polyfills, etc.).

Installation

npm install @form-guardian/core

Features

• ✅ IndexedDB Storage - Persistent storage for form drafts
• ✅ TTL Support - Automatic expiration of drafts
• ✅ Draft Management - Save, load, check, and clear drafts
• ✅ Framework Agnostic - Works with any JavaScript framework or vanilla JS
• ✅ TypeScript Support - Full type definitions included

API

saveDraftCore<T>(draftId, values, options?)

Save form values as a draft.

import { saveDraftCore } from '@form-guardian/core';

await saveDraftCore('my-form', { name: 'John', email: '[email protected]' }, {
  formId: 'my-form',
  origin: window.location.origin,
  ttl: { days: 7 }
});

loadDraftCore<T>(draftId, options?)

Load a saved draft.

import { loadDraftCore } from '@form-guardian/core';

const draft = await loadDraftCore('my-form', { ttl: { days: 7 } });
if (draft) {
  console.log(draft.values); // { name: 'John', email: '[email protected]' }
  console.log(draft.updatedAt); // timestamp
}

hasDraftCore(draftId)

Check if a draft exists.

import { hasDraftCore } from '@form-guardian/core';

const exists = await hasDraftCore('my-form');

clearDraft(draftId)

Remove a draft from storage.

import { clearDraft } from '@form-guardian/core';

await clearDraft('my-form');

makeDraftId(formId, options?)

Generate a unique draft ID with optional origin and prefix.

import { makeDraftId } from '@form-guardian/core';

const draftId = makeDraftId('my-form', {
  includeOrigin: true,
  prefix: 'fg'
});

debounce(func, wait)

Utility function for debouncing function calls.

import { debounce } from '@form-guardian/core';

const debouncedSave = debounce((values) => {
  saveDraftCore('my-form', values);
}, 500);

Storage

The package uses IndexedDBStorage by default, which implements the DraftStorage interface. You can also create custom storage implementations:

import type { DraftStorage, DraftData } from '@form-guardian/core';

class CustomStorage implements DraftStorage {
  async save<T>(draftId: string, data: DraftData<T>): Promise<void> {
    // Custom save logic
  }
  
  async load<T>(draftId: string): Promise<DraftData<T> | null> {
    // Custom load logic
  }
  
  async remove(draftId: string): Promise<void> {
    // Custom remove logic
  }
  
  async has(draftId: string): Promise<boolean> {
    // Custom has logic
  }
}

TTL (Time To Live)

Drafts can automatically expire after a specified time:

// Expire after 7 days
await saveDraftCore('my-form', values, {
  ttl: { days: 7 }
});

// Expire after 2 hours
await saveDraftCore('my-form', values, {
  ttl: { hours: 2 }
});

// Expire after 30 minutes
await saveDraftCore('my-form', values, {
  ttl: { minutes: 30 }
});

// Expire after specific milliseconds
await saveDraftCore('my-form', values, {
  ttl: 86400000 // 1 day in milliseconds
});

When to Use

Use @form-guardian/core directly if you:

• Need low-level control over draft storage
• Are building a custom integration
• Want to implement your own DOM/form handling logic
• Are working in a non-browser environment (with polyfills)

For most use cases, consider using:

• @form-guardian/dom - for universal DOM-based autosave
• @form-guardian/react - for React-specific hooks