restate / v1.0.0

Зберігайте, коли вирішите

Тримайте сховище в IndexedDB або MMKV, завантажуйте його один раз під час запуску, зберігайте явно або автоматично й показуйте незбережені правки.

На цій сторінці

Оголошення збережуваного сховища Очікування один раз під час запуску Збереження, скасування й скидання Показ незбережених правок і перебігу Спробуйте Автоматичне збереження Перед закриттям сторінки Обробка помилок сховища

Оголошення збережуваного сховища

Замініть restate на persistedRestate і задайте key. Компоненти й далі використовують той самий хук і той самий set.

Збережене значення відновлюється автоматично після створення. Правка змінює пам’ять; нічого не записується, доки ви не збережете або не ввімкнете autoSave.

import { persistedRestate } from '@kkwaenggwari/restate';

export const useDraft = persistedRestate('', {
  key: 'article-draft',
  validate: (value) => typeof value === 'string',
});

Очікування один раз під час запуску

У клієнтській точці входу імпортуйте застосунок і його сховища, потім дочекайтеся restateManager.ready перед рендером. Відтак компоненти можуть одразу читати збережені значення.

Недоступне сховище — наприклад, під час рендерингу на сервері чи в браузері, який його блокує, — не помилка: такі сховища працюють у пам’яті. ready відхиляється, лише коли записи не можна прочитати, мігрувати чи перевірити.

import { createRoot } from 'react-dom/client';
import { restateManager } from '@kkwaenggwari/restate';
import App from './App';

async function start() {
  const root = createRoot(document.getElementById('root'));
  try {
    await restateManager.ready;
    root.render(<App />);
  } catch (error) {
    root.render(<p>Could not load saved data.</p>);
    console.error(error);
  }
}
start();

Збереження, скасування й скидання

save записує поточне значення, restore повертає збережене, а resetAll очищає і пам’ять, і сховище. Кожен повертає Promise.

await useDraft.save(); // write the current value
await useDraft.restore(); // return to the saved value
await useDraft.resetAndClearStorage(); // initial value in memory, record removed

Показ незбережених правок і перебігу

useStatus перемальовується, коли змінюється статус збереження. dirty дорівнює true, доки пам’ять відрізняється від останнього завантаженого, збереженого чи відновленого значення. operation називає поточну операцію зі сховищем.

Передайте selector, щоб перемальовувати лише за зміни одного поля.

Поля статусу

dirty      true | false
operation  "save" | "restore" | … | null
pending    number of unsettled operations
error      last storage error or null
available  false when storage cannot be used

Невдале збереження лишає dirty рівним true і заповнює error. Наступна успішна операція зі сховищем очищає error.

function SaveButton() {
  const { dirty, operation, error } = useDraft.useStatus();
  const saving = operation === 'save';

  return (
    <>
      <button disabled={!dirty || saving} onClick={() => useDraft.save().catch(() => {})}>
        {saving ? 'Saving…' : 'Save'}
      </button>
      {error != null && <p>Could not save your draft.</p>}
    </>
  );
}

Спробуйте

Друкуйте, збільште затримку сховища й збережіть. Повторіть приклад, щоб побачити відновлену чернетку.

КонтролерНе входить до коду прикладу. Значення потрапляють у приклад як props.

Затримка сховищаlatency

<Example
  latency={600}
/>

Підготовка прикладу…

Для живих прикладів потрібен JavaScript. Код нижче можна читати як є.

App.jsx

import { useEffect } from 'react';
import { persistedRestate } from '@kkwaenggwari/restate';
import { settings, slowStorage } from './storage.js';
import './styles.css';

const useDraft = persistedRestate('', { key: 'playground-draft', storage: slowStorage });

export default function Example({ latency = 600 }) {
  useEffect(() => {
    settings.latency = latency;
  }, [latency]);

  const text = useDraft();
  const { dirty, operation, pending, lastSavedAt } = useDraft.useStatus();
  // A failed save keeps dirty and records status.error.
  const save = () => useDraft.save().catch(() => {});
  const revert = () => useDraft.restore().catch(() => {});

  return (
    <main>
      <label>
        Чернетка
        <textarea value={text} onChange={(event) => useDraft.set(event.target.value)} />
      </label>
      <div className="actions">
        <button disabled={!dirty} onClick={save}>
          Зберегти
        </button>
        <button disabled={!dirty} onClick={revert}>
          Скасувати правки
        </button>
      </div>
      <dl className="status">
        <dt>dirty</dt>
        <dd className={dirty ? 'warn' : 'ok'}>{dirty ? 'незбережені правки' : 'збережено'}</dd>
        <dt>operation</dt>
        <dd>{operation ?? 'немає'}</dd>
        <dt>pending</dt>
        <dd>{pending}</dd>
        <dt>lastSavedAt</dt>
        <dd>{lastSavedAt ? new Date(lastSavedAt).toLocaleTimeString() : 'ще ні'}</dd>
      </dl>
    </main>
  );
}

storage.js

import { createIndexedDBStorage } from '@kkwaenggwari/restate';

// IndexedDB with an adjustable delay, to watch operations in progress.
const indexedDB = createIndexedDBStorage();
export const settings = { latency: 0 };
const wait = () => new Promise((resolve) => setTimeout(resolve, settings.latency));

export const slowStorage = {
  async getItem(key) {
    await wait();
    return indexedDB.getItem(key);
  },
  async setItem(key, value) {
    await wait();
    return indexedDB.setItem(key, value);
  },
  async removeItem(key) {
    await wait();
    return indexedDB.removeItem(key);
  },
};

Автоматичне збереження

Для налаштувань і чернеток, які завжди мають зберігатися, увімкніть його один раз. autoSave: true зберігає після кожної зміни; { delayMs } чекає, доки правки припиняться.

Серія правок перетворюється на один запис, а повернення до збереженого значення нічого не пише. Помилки з’являються в status().error. Область компонента записує незавершену правку під час демонтування.

export const useTheme = persistedRestate('light', { key: 'theme', autoSave: true });

export const useDraft = persistedRestate('', {
  key: 'article-draft',
  autoSave: { delayMs: 500 },
});

Перед закриттям сторінки

Читайте той самий стан поза React. Попереджайте перед виходом, якщо є незбережені правки, або зберігайте все, коли сторінка ховається.

window.addEventListener('beforeunload', (event) => {
  if (useDraft.status().dirty) event.preventDefault();
});

window.addEventListener('pagehide', () => {
  restateManager.saveAll();
});

Обробка помилок сховища

Помилки сховища відхиляють Promise операції. Кожна помилка restate має code, а збережувані сховища — ще й key запису.

try {
  await useDraft.save();
} catch (error) {
  if (error.code === 'STORAGE_UNAVAILABLE') showNotice('Saving is off in this browser.');
  else if (error.code === 'STORAGE_VALUE_TOO_LARGE') showNotice('This draft is too large.');
  else showNotice(`Could not save "${error.key ?? 'draft'}".`);
}

Написано для API restate 1.0