restate / v1.0.0

Simpan saat Anda memutuskan

Simpan store di IndexedDB atau MMKV, muat sekali saat mulai, simpan secara eksplisit atau otomatis, dan tampilkan perubahan yang belum tersimpan.

Di halaman ini

Mendeklarasikan store tersimpan Tunggu sekali saat mulai Simpan, batalkan, dan atur ulang Menampilkan perubahan belum tersimpan dan progres Coba Simpan otomatis Sebelum halaman ditutup Menangani kesalahan penyimpanan

Mendeklarasikan store tersimpan

Ganti restate dengan persistedRestate dan beri key. Komponen tetap memakai hook dan set yang sama.

Nilai tersimpan dipulihkan otomatis setelah dibuat. Mengedit mengubah memori; tidak ada yang ditulis sampai Anda menyimpan atau mengaktifkan autoSave.

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

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

Tunggu sekali saat mulai

Di titik masuk klien, impor aplikasi dan store-nya, lalu tunggu restateManager.ready sebelum merender. Setelah itu komponen dapat membaca nilai tersimpan secara langsung.

Penyimpanan yang tidak tersedia, misalnya saat server rendering atau di browser yang memblokirnya, bukan kesalahan: store seperti itu berjalan di memori. ready hanya ditolak bila catatan tidak dapat dibaca, dimigrasi, atau divalidasi.

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();

Simpan, batalkan, dan atur ulang

save menulis nilai saat ini, restore kembali ke nilai tersimpan, dan resetAll membersihkan memori dan penyimpanan. Masing-masing mengembalikan 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

Menampilkan perubahan belum tersimpan dan progres

useStatus dirender ulang saat status penyimpanan berubah. dirty bernilai true selama memori berbeda dari nilai terakhir yang dimuat, disimpan, atau dipulihkan. operation menyebut operasi penyimpanan saat ini.

Berikan selector agar hanya dirender ulang saat satu field berubah.

Field status

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

Penyimpanan yang gagal membiarkan dirty bernilai true dan mengisi error. Operasi penyimpanan berikutnya yang berhasil membersihkan 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>}
    </>
  );
}

Coba

Ketik, naikkan penundaan penyimpanan, lalu simpan. Putar ulang contoh untuk melihat draf yang dipulihkan.

PengontrolBukan bagian dari kode contoh. Nilainya masuk ke contoh sebagai props.

Penundaan penyimpananlatency

<Example
  latency={600}
/>

Menyiapkan contoh…

Contoh langsung memerlukan JavaScript. Kode di bawah bisa Anda baca apa adanya.

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>
        Draf
        <textarea value={text} onChange={(event) => useDraft.set(event.target.value)} />
      </label>
      <div className="actions">
        <button disabled={!dirty} onClick={save}>
          Simpan
        </button>
        <button disabled={!dirty} onClick={revert}>
          Buang perubahan
        </button>
      </div>
      <dl className="status">
        <dt>dirty</dt>
        <dd className={dirty ? 'warn' : 'ok'}>
          {dirty ? 'perubahan belum tersimpan' : 'tersimpan'}
        </dd>
        <dt>operation</dt>
        <dd>{operation ?? 'tidak ada'}</dd>
        <dt>pending</dt>
        <dd>{pending}</dd>
        <dt>lastSavedAt</dt>
        <dd>{lastSavedAt ? new Date(lastSavedAt).toLocaleTimeString() : 'belum'}</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);
  },
};

Simpan otomatis

Aktifkan sekali untuk pengaturan dan draf yang harus selalu tersimpan. autoSave: true menyimpan setelah setiap perubahan; { delayMs } menunggu sampai perubahan berhenti.

Rentetan perubahan menjadi satu penulisan, dan kembali ke nilai tersimpan tidak menulis apa pun. Kesalahan muncul di status().error. Scope komponen menulis perubahan tertunda saat unmount.

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

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

Sebelum halaman ditutup

Baca status yang sama di luar React. Peringatkan perubahan yang belum tersimpan sebelum pergi, atau simpan semuanya saat halaman disembunyikan.

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

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

Menangani kesalahan penyimpanan

Kesalahan penyimpanan menolak Promise operasinya. Setiap kesalahan restate punya code, dan untuk store tersimpan juga key catatannya.

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'}".`);
}

Ditulis untuk API restate 1.0