Перейти к основному содержимому

@form-guardian/core

Headless ядро для управления черновиками. Не зависит от фреймворков.

Установка​

npm install @form-guardian/core

saveDraftCore(draftId, values, options?)​

Сохранить черновик в хранилище.

Импорт:

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

Параметры:

  • draftId (string) - Уникальный идентификатор черновика
  • values (T) - Значения для сохранения
  • options (object, опциональный) - Опции хранилища
    • formId (string, опциональный) - Идентификатор формы
    • origin (string, опциональный) - URL источника
    • ttl (number | object, опциональный) - Время жизни

Возвращает: Promise<void>

Пример:

await saveDraftCore('form-id', 
  { name: 'Иван', email: 'ivan@example.com' },
  {
    formId: 'contact-form',
    origin: 'https://example.com',
    ttl: { days: 7 },
  }
);

loadDraftCore(draftId, options?)​

Загрузить черновик из хранилища.

Импорт:

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

Параметры:

  • draftId (string) - Уникальный идентификатор черновика
  • options (object, опциональный) - Опции хранилища

Возвращает: Promise<DraftData<T> | null>

Пример:

const draft = await loadDraftCore('form-id');
if (draft) {
  console.log(draft.values); // { name: 'Иван', email: 'ivan@example.com' }
  console.log(draft.updatedAt); // 1699564800000
  console.log(draft.formId); // 'contact-form'
  console.log(draft.origin); // 'https://example.com'
}

clearDraft(draftId, options?)​

Очистить черновик из хранилища.

Импорт:

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

Параметры:

  • draftId (string) - Уникальный идентификатор черновика
  • options (object, опциональный) - Опции хранилища

Возвращает: Promise<void>

Пример:

await clearDraft('form-id');

hasDraftCore(draftId, options?)​

Проверить, существует ли черновик.

Импорт:

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

Параметры:

  • draftId (string) - Уникальный идентификатор черновика
  • options (object, опциональный) - Опции хранилища

Возвращает: Promise<boolean>

Пример:

const exists = await hasDraftCore('form-id');
if (exists) {
  console.log('Черновик найден!');
}

makeDraftId(formId, options?)​

Сгенерировать ID черновика из ID формы и опций.

Импорт:

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

Параметры:

  • formId (string) - Идентификатор формы
  • options (object, опциональный) - Конфигурация
    • includeOrigin (boolean) - Включить origin в ID (по умолчанию: true)
    • prefix (string) - Префикс ключа хранилища (по умолчанию: 'fg')

Возвращает: string

Пример:

const draftId = makeDraftId('my-form', {
  includeOrigin: true,
  prefix: 'fg',
});
// Возвращает: 'fg:https://example.com:my-form'

// Без origin
const simpleId = makeDraftId('my-form', {
  includeOrigin: false,
  prefix: 'app',
});
// Возвращает: 'app:my-form'

Типы​

DraftData<T>​

Структура данных черновика, возвращаемая loadDraftCore.

interface DraftData<T> {
  values: T;                // Значения черновика
  updatedAt: number;        // Временная метка
  formId?: string;          // Идентификатор формы
  origin?: string;          // URL источника
  ttl?: number | {          // Время жизни
    days?: number;
    hours?: number;
    minutes?: number;
  };
}

DraftMeta​

Метаданные черновика без значений.

interface DraftMeta {
  updatedAt: number;
  formId?: string;
  origin?: string;
  ttl?: number | { days?: number; hours?: number; minutes?: number };
}

Примеры использования​

Кастомный менеджер хранилища​

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

class CustomDraftManager {
  async save(formId: string, values: any) {
    const draftId = `custom:${formId}`;
    await saveDraftCore(draftId, values, {
      formId,
      ttl: { hours: 24 },
    });
  }

  async load(formId: string) {
    const draftId = `custom:${formId}`;
    const draft = await loadDraftCore(draftId);
    return draft?.values || null;
  }

  async clear(formId: string) {
    const draftId = `custom:${formId}`;
    await clearDraft(draftId);
  }
}

const manager = new CustomDraftManager();
await manager.save('contact-form', { name: 'Иван' });
const values = await manager.load('contact-form');
await manager.clear('contact-form');

Серверный рендеринг (SSR)​

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

// Проверка статуса черновика на сервере
export async function getServerSideProps({ req }) {
  const formId = 'user-profile';
  const draftId = `fg:${req.headers.origin}:${formId}`;
  
  const hasDraft = await hasDraftCore(draftId);
  
  return {
    props: {
      hasDraft,
      formId,
    },
  };
}

// Клиентская сторона: загрузить черновик если существует
function ProfileForm({ hasDraft, formId }) {
  useEffect(() => {
    if (hasDraft) {
      loadDraftCore(formId).then(draft => {
        if (draft) {
          // Заполнить форму значениями draft.values
        }
      });
    }
  }, [hasDraft, formId]);
  
  // ...
}

Синхронизация черновиков​

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

class DraftSync {
  async syncToServer(formId: string) {
    const draft = await loadDraftCore(formId);
    if (!draft) return;

    // Отправить на сервер
    await fetch('/api/drafts', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        formId: draft.formId,
        values: draft.values,
        updatedAt: draft.updatedAt,
      }),
    });
  }

  async syncFromServer(formId: string) {
    const response = await fetch(`/api/drafts/${formId}`);
    const serverDraft = await response.json();
    
    if (serverDraft) {
      await saveDraftCore(formId, serverDraft.values, {
        formId: serverDraft.formId,
      });
    }
  }
}

Связанные материалы​