npm package: @form-guardian/core
Description: Headless core library for form autosave functionality. Provides IndexedDB storage, draft management, and TTL support. Framework-agnostic and works with any JavaScript environment.
Author: Tishkin Yuri
Latest version: 1.0.5

# @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

```bash
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.

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

await saveDraftCore('my-form', { name: 'John', email: 'john@example.com' }, {
  formId: 'my-form',
  origin: window.location.origin,
  ttl: { days: 7 }
});
```

### `loadDraftCore<T>(draftId, options?)`

Load a saved draft.

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

const draft = await loadDraftCore('my-form', { ttl: { days: 7 } });
if (draft) {
  console.log(draft.values); // { name: 'John', email: 'john@example.com' }
  console.log(draft.updatedAt); // timestamp
}
```

### `hasDraftCore(draftId)`

Check if a draft exists.

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

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

### `clearDraft(draftId)`

Remove a draft from storage.

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

await clearDraft('my-form');
```

### `makeDraftId(formId, options?)`

Generate a unique draft ID with optional origin and prefix.

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

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

### `debounce(func, wait)`

Utility function for debouncing function calls.

```typescript
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:

```typescript
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:

```typescript
// 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