restate / v1.0.0

Tasarımdan güvenilir

Depolama yavaş olduğunda, başarısız olduğunda ya da hiç olmadığında restate neyi garanti eder ve bildirdiği hatalar nasıl okunur.

Bu sayfada

Garantiler Sıralı kaydetmeler Deneyin Yükleme başarısız olduğunda Kaydet ve kapat Depolama kullanılamıyor Kayıtlı verileri doğrulamak ve taşımak Kendi depolamanız Sınırlar ve zaman aşımları Hata kodları

Garantiler

Bu davranış 1.0 sözleşmesinin parçasıdır ve paketin testleriyle kapsanır.

Durum	restate ne yapar
`Art arda birkaç kaydetme`	Bunları her store için sırayla çalıştırır; kuyruktaki kaydetme en son değeri yazar.
`Bir kayıt yüklenemedi`	autoSave ve toplu kaydetmeler LOAD_FAILED ile onu atlar; yalnızca açık bir save() onu değiştirir.
`Kaydetme sırasında bileşen ayrılır`	İstenen kaydetme tamamlanır; yok edilmiş store'a sonraki yazmalar yok sayılır.
`Depolama kullanılamıyor`	Store bellekte çalışır, status().available false olur ve kaydetmeler reddedilir.
`Adaptör takılır`	İşlem operationTimeoutMs sonunda zaman aşımına uğrar ve sonraki işler adaptörün bitmesini bekler.
`Çok fazla bekleyen iş`	Yeni işlemler sınırsızca büyümek yerine QUEUE_FULL ile reddedilir.

Sıralı kaydetmeler

Bir store'un işlemleri asla çakışmaz. Başkası beklerken başlayan bir kaydetme en son değeri alır; böylece her değişiklikte kaydetmek kuyruğu doldurmadan son durumu yazar.

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

Deneyin

Depolamayı yavaşlatın, yazmaları başarısız kılın ya da depolamayı tamamen kaldırın.

DenetleyiciÖrnek kodun parçası değildir. Değerler örneğe props olarak ulaşır.

Gecikmelatency
Başarısız yazmalarfailWrites
Depolama kullanılamıyorunavailable

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

Örnek hazırlanıyor…

Canlı örnekler JavaScript gerektirir. Aşağıdaki kodu olduğu gibi okuyabilirsiniz.

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) => [`Kaydedildi: ${JSON.stringify(value)}`, ...list]),
      (reason) => setResults((list) => [`Başarısız: ${reason.code ?? reason.message}`, ...list]),
    );

  return (
    <main>
      <label>
        Not
        <input value={note} onChange={(event) => useNote.set(event.target.value)} />
      </label>
      <div className="actions">
        <button onClick={save}>Kaydet</button>
        <button
          onClick={() => {
            save();
            save();
            save();
          }}
        >
          Üç kez kaydet
        </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>Sonuçlar</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 dolu');
    records.set(key, value);
  },
  async removeItem(key) {
    await wait();
    records.delete(key);
  },
};

Yükleme başarısız olduğunda

restateManager.ready BULK_OPERATION_FAILED ile reddedilir ve başarısız olan her store'u listeler. O kayıt yüklenene kadar autoSave ve saveAll onu değiştirmez ve LOAD_FAILED bildirir.

Değişiklikleri tutup kaydetmek için initialize() ile yeniden deneyin, atmak için restore() çağırın ya da kaydı bilerek değiştirmek için save() kullanın.

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

Kaydet ve kapat

Ayrılmadan önce istenen kaydetme yine de tamamlanır; bu yüzden "Kaydet ve kapat" işleyicisinin beklemesi gerekmez.

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

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

Depolama kullanılamıyor

Sunucu tarafı render ve tarayıcının engellediği depolama başlangıç hatası değildir. Kullanıcılara değişikliklerin yalnızca bellekte kaldığını söylemek için available'ı kontrol edin.

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

Kayıtlı verileri doğrulamak ve taşımak

version, migrate ve validate sizi eski ya da bozuk kayıtlardan korur. validate kaydetmeden önce ve geri yükleme ya da taşıma sonrasında çalışır.

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),
  },
);

Kendi depolamanız

getItem, setItem ve removeItem içeren her nesne kullanılabilir. Metotlar değer ya da Promise döndürebilir; isAvailable isteğe bağlıdır.

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,
  },
);

Sınırlar ve zaman aşımları

Bir işlemin ne kadar sürebileceğini, kaç tanesinin bekleyebileceğini ve bir değerin ne kadar büyük olabileceğini ayarlayın.

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

Hata kodları

restate'in oluşturduğu hataların name'i RestateError'dır; code'ları ve kayıtlı store'larda key'leri vardır. Depolama adaptörleri ve callback'leriniz kendi hatalarıyla reddedebilir.

Kod	Anlamı
`BULK_OPERATION_FAILED`	restateManager.ready ya da saveAll gibi toplu bir çağrıda hata oluştu; error.failures'a bakın.
`INDEXEDDB_ABORTED`	Bir IndexedDB işlemi iptal edildi.
`INDEXEDDB_BLOCKED`	Veritabanının açılması başka bir sekmedeki bağlantı tarafından engellendi.
`INDEXEDDB_CONNECTION_CLOSING`	İstek başladığında veritabanı bağlantısı kapanıyordu.
`INDEXEDDB_OPEN_FAILED`	Veritabanı açılamadı.
`INDEXEDDB_REQUEST_FAILED`	Bir IndexedDB isteği başarısız oldu.
`INDEXEDDB_STORE_MISSING`	Önceden var olan veritabanında object store eksik.
`INVALID_STORAGE_RECORD`	Kayıtlı kayıt geçerli bir restate kaydı değil.
`INVALID_STORED_VALUE`	Değer validate'ten geçemedi.
`LIFECYCLE_LIMIT`	Bir updater sürekli başlayıp durdu.
`LOAD_FAILED`	Kayıt yüklenemedi; bu yüzden otomatik ya da toplu kaydetme onu değiştirmedi.
`MMKV_UNAVAILABLE`	react-native-mmkv yüklenemedi.
`MULTIPLE_ERRORS`	Tek bir işlemde birkaç callback başarısız oldu; error.errors'a bakın.
`NOTIFICATION_LIMIT`	Gözlemciler bir döngü içinde sürekli değişiklik planladı.
`OBSERVER_ERROR`	Bir listener ya da yaşam döngüsü callback'i hata fırlattı.
`OPERATION_ABORTED`	Bir depolama işlemi iptal edildi.
`QUEUE_FULL`	maxPendingOperations'ın izin verdiğinden fazla işlem bekliyordu.
`REENTRANT_SETTER`	Bir durum updater'ı çalışırken aynı store'u değiştirmeye çalıştı.
`SCOPE_DESTROYED`	Store oluşturmak için yok edilmiş bir scope kullanıldı.
`SEQUENCE_EXHAUSTED`	Dahili bir dizinin tanımlayıcıları tükendi.
`STORAGE_BLOCKED`	Önceki bir adaptör çağrısı zaman aşımı ya da iptalden sonra tamamlanmadı.
`STORAGE_TIMEOUT`	Bir işlem operationTimeoutMs'den uzun sürdü.
`STORAGE_UNAVAILABLE`	Burada depolama kullanılamıyor; store bellekte çalışmayı sürdürür.
`STORAGE_VALUE_TOO_LARGE`	Kodlanmış değer maxStorageCharacters'ı aşıyor.
`STORAGE_VERSION_MISMATCH`	Kaydın sürümü farklı ve onu hiçbir migrate fonksiyonu işlemiyor.
`STORE_DESTROYED`	Yok edilmiş bir store'a abone olundu ya da ondan depolama kullanması istendi.

restate 1.0 API'si için yazıldı