restate / v1.0.0

Andal sejak rancangan

Apa yang dijamin restate saat penyimpanan lambat, gagal, atau tidak ada, dan cara membaca kesalahan yang dilaporkannya.

Di halaman ini

Jaminan Penyimpanan berurutan Coba Saat pemuatan gagal Simpan dan tutup Penyimpanan tidak tersedia Memvalidasi dan memigrasi data tersimpan Penyimpanan sendiri Batas dan batas waktu Kode kesalahan

Jaminan

Perilaku ini adalah bagian dari kontrak 1.0 dan dicakup oleh test paket.

Situasi	Yang dilakukan restate
`Beberapa penyimpanan berturut-turut`	Menjalankannya berurutan per store; penyimpanan dalam antrean menulis nilai terbaru.
`Catatan gagal dimuat`	autoSave dan penyimpanan massal melewatinya dengan LOAD_FAILED; hanya save() eksplisit yang menggantinya.
`Komponen unmount saat menyimpan`	Penyimpanan yang diminta selesai; penulisan berikutnya ke store yang sudah dihancurkan diabaikan.
`Penyimpanan tidak tersedia`	Store berjalan di memori, status().available bernilai false, dan penyimpanan ditolak.
`Adaptor macet`	Operasi habis waktu setelah operationTimeoutMs, dan pekerjaan berikutnya menunggu adaptor selesai.
`Terlalu banyak pekerjaan tertunda`	Operasi baru ditolak dengan QUEUE_FULL alih-alih tumbuh tanpa batas.

Operasi satu store tidak pernah tumpang-tindih. Penyimpanan yang dimulai saat yang lain menunggu mengambil nilai terbaru, sehingga menyimpan pada setiap perubahan menulis state terakhir tanpa memenuhi antrean.

useDraft.set('A');
const first = useDraft.save(); // writes "A"
useDraft.set('B');
const second = useDraft.save(); // waits in the queue
useDraft.set('C');
const third = useDraft.save(); // joins the waiting save

await Promise.all([first, second, third]); // ['A', 'C', 'C'] — two writes

Coba

Perlambat penyimpanan, buat penulisan gagal, atau hilangkan penyimpanan sama sekali.

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

Penundaanlatency
Penulisan gagalfailWrites
Penyimpanan tidak tersediaunavailable

<Example
  latency={700}
  failWrites={false}
  unavailable={false}
/>

Menyiapkan contoh…

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

App.jsx

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

const useNote = persistedRestate('', { key: 'lab-note', storage: flakyStorage });

export default function Example({ latency = 700, failWrites = false, unavailable = false }) {
  useEffect(() => {
    Object.assign(settings, { latency, failWrites, unavailable });
  }, [latency, failWrites, unavailable]);

  const note = useNote();
  const { dirty, operation, pending, error } = useNote.useStatus();
  const [results, setResults] = useState([]);

  const save = () =>
    useNote.save().then(
      (value) => setResults((list) => [`Tersimpan: ${JSON.stringify(value)}`, ...list]),
      (reason) => setResults((list) => [`Gagal: ${reason.code ?? reason.message}`, ...list]),
    );

  return (
    <main>
      <label>
        Catatan
        <input value={note} onChange={(event) => useNote.set(event.target.value)} />
      </label>
      <div className="actions">
        <button onClick={save}>Simpan</button>
        <button
          onClick={() => {
            save();
            save();
            save();
          }}
        >
          Simpan tiga kali
        </button>
      </div>
      <dl className="status">
        <dt>dirty</dt>
        <dd className={dirty ? 'warn' : 'ok'}>{String(dirty)}</dd>
        <dt>operation</dt>
        <dd>{operation ?? '-'}</dd>
        <dt>pending</dt>
        <dd>{pending}</dd>
        <dt>error</dt>
        <dd className={error ? 'bad' : ''}>{error ? (error.code ?? error.message) : '-'}</dd>
      </dl>
      <h2>Hasil</h2>
      <ol className="log">
        {results.length ? (
          results.map((result, index) => <li key={results.length - index}>{result}</li>)
        ) : (
          <li>-</li>
        )}
      </ol>
    </main>
  );
}

storage.js

// A storage adapter whose speed and failures you can change.
const records = new Map();
export const settings = { latency: 0, failWrites: false, unavailable: false };
const wait = () => new Promise((resolve) => setTimeout(resolve, settings.latency));

export const flakyStorage = {
  isAvailable: () => !settings.unavailable,
  async getItem(key) {
    await wait();
    return records.get(key) ?? null;
  },
  async setItem(key, value) {
    await wait();
    if (settings.failWrites) throw new Error('Disk penuh');
    records.set(key, value);
  },
  async removeItem(key) {
    await wait();
    records.delete(key);
  },
};

Saat pemuatan gagal

restateManager.ready ditolak dengan BULK_OPERATION_FAILED dan mencantumkan setiap store yang gagal. Sampai catatan itu dimuat, autoSave dan saveAll tidak menggantinya dan melaporkan LOAD_FAILED.

Coba lagi dengan initialize() untuk mempertahankan perubahan lalu menyimpannya, panggil restore() untuk membuangnya, atau save() untuk sengaja menimpa catatan.

try {
  await restateManager.ready;
} catch (error) {
  // BULK_OPERATION_FAILED: one entry per store that could not load.
  for (const { store, error: cause } of error.failures) {
    console.error(store.key, cause.code);
  }
}

Simpan dan tutup

Penyimpanan yang diminta sebelum unmount tetap selesai, jadi handler "Simpan dan tutup" tidak perlu menunggu.

function Document({ onClose }) {
  const useDraft = useRestateScope((scope) => persistedRestate('', { scope, key: 'draft' }));

  const saveAndClose = () => {
    useDraft.save(); // finishes even after this component unmounts
    onClose();
  };
  // …
}

Penyimpanan tidak tersedia

Server rendering dan penyimpanan yang diblokir browser bukan kesalahan saat mulai. Periksa available untuk memberi tahu pengguna bahwa perubahan hanya ada di memori.

const { available } = useDraft.status();

if (!available) {
  // Server rendering or blocked browser storage: the store works in memory
  // and save() rejects with STORAGE_UNAVAILABLE.
  showNotice('Changes are kept until you close this tab.');
}

Memvalidasi dan memigrasi data tersimpan

version, migrate, dan validate melindungi Anda dari catatan lama atau rusak. validate berjalan sebelum menyimpan dan setelah pemulihan atau migrasi.

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

const useSettings = persistedRestate(
  { theme: 'system' },
  {
    key: 'settings',
    version: 2,
    migrate(value, from, to) {
      if (from === 1 && to === 2 && typeof value?.darkMode === 'boolean') {
        return { theme: value.darkMode ? 'dark' : 'light' };
      }
      throw new Error('Unsupported stored version');
    },
    validate: (value) => ['system', 'light', 'dark'].includes(value?.theme),
  },
);

Penyimpanan sendiri

Objek apa pun dengan getItem, setItem, dan removeItem bisa dipakai. Metodenya boleh mengembalikan nilai atau Promise; isAvailable opsional.

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

const sessionStorageAdapter = {
  isAvailable: () => typeof sessionStorage !== 'undefined',
  getItem: (key) => sessionStorage.getItem(key),
  setItem: (key, value) => sessionStorage.setItem(key, value),
  removeItem: (key) => sessionStorage.removeItem(key),
};

export const useFilters = persistedRestate(
  { query: '' },
  {
    key: 'filters',
    storage: sessionStorageAdapter,
  },
);

Batas dan batas waktu

Atur berapa lama sebuah operasi boleh berjalan, berapa banyak yang boleh menunggu, dan seberapa besar sebuah nilai.

persistedRestate(value, {
  key: 'draft',
  operationTimeoutMs: 10_000, // default 30000
  maxPendingOperations: 64, // default 256
  maxStorageCharacters: 1_000_000,
});

Kode kesalahan

Kesalahan yang dibuat restate punya name RestateError, code, dan untuk store tersimpan key. Adaptor penyimpanan dan callback Anda dapat menolak dengan kesalahannya sendiri.

Kode	Arti
`BULK_OPERATION_FAILED`	Panggilan massal seperti restateManager.ready atau saveAll mengalami kegagalan; lihat error.failures.
`INDEXEDDB_ABORTED`	Transaksi IndexedDB dibatalkan.
`INDEXEDDB_BLOCKED`	Pembukaan database diblokir oleh koneksi di tab lain.
`INDEXEDDB_CONNECTION_CLOSING`	Koneksi database sedang ditutup saat permintaan dimulai.
`INDEXEDDB_OPEN_FAILED`	Database tidak dapat dibuka.
`INDEXEDDB_REQUEST_FAILED`	Permintaan IndexedDB gagal.
`INDEXEDDB_STORE_MISSING`	Database yang sudah ada tidak memiliki object store.
`INVALID_STORAGE_RECORD`	Catatan tersimpan bukan catatan restate yang valid.
`INVALID_STORED_VALUE`	Nilai tidak lolos validate.
`LIFECYCLE_LIMIT`	Updater terus dimulai dan dihentikan.
`LOAD_FAILED`	Catatan tidak dapat dimuat, jadi penyimpanan otomatis atau massal tidak menggantinya.
`MMKV_UNAVAILABLE`	react-native-mmkv tidak dapat dimuat.
`MULTIPLE_ERRORS`	Beberapa callback gagal dalam satu operasi; lihat error.errors.
`NOTIFICATION_LIMIT`	Observer terus menjadwalkan perubahan dalam putaran.
`OBSERVER_ERROR`	Listener atau callback siklus hidup melempar kesalahan.
`OPERATION_ABORTED`	Operasi penyimpanan dibatalkan.
`QUEUE_FULL`	Operasi yang menunggu lebih banyak dari yang diizinkan maxPendingOperations.
`REENTRANT_SETTER`	Updater state mencoba mengubah store yang sama saat sedang berjalan.
`SCOPE_DESTROYED`	Scope yang sudah dihancurkan dipakai untuk membuat store.
`SEQUENCE_EXHAUSTED`	Urutan internal kehabisan pengenal.
`STORAGE_BLOCKED`	Panggilan adaptor sebelumnya belum selesai setelah habis waktu atau dibatalkan.
`STORAGE_TIMEOUT`	Operasi berlangsung lebih lama dari operationTimeoutMs.
`STORAGE_UNAVAILABLE`	Penyimpanan tidak dapat dipakai di sini; store tetap berjalan di memori.
`STORAGE_VALUE_TOO_LARGE`	Nilai yang dienkode melebihi maxStorageCharacters.
`STORAGE_VERSION_MISMATCH`	Catatan punya versi berbeda dan tidak ada fungsi migrate yang menanganinya.
`STORE_DESTROYED`	Store yang sudah dihancurkan dilanggani atau diminta memakai penyimpanan.

Ditulis untuk API restate 1.0