restate / v1.0.0

Megbízható tervezésből fakadóan

Mit garantál a restate, ha a tároló lassú, meghibásodik vagy hiányzik, és hogyan olvassa a jelzett hibákat.

Ezen az oldalon

Garanciák Mentések sorrendben Próbálja ki Ha a betöltés sikertelen Mentés és bezárás A tároló nem érhető el Mentett adatok ellenőrzése és migrálása Saját tároló Korlátok és időtúllépések Hibakódok

Garanciák

Ez a viselkedés az 1.0 szerződés része, és a csomag tesztjei lefedik.

Helyzet	Mit tesz a restate
`Több mentés egymás után`	Store-onként sorban futtatja őket; a sorban álló mentés a legújabb értéket írja ki.
`Egy rekord nem töltődött be`	Az autoSave és a tömeges mentések LOAD_FAILED hibával kihagyják; csak egy kifejezett save() cseréli le.
`A komponens mentés közben leválik`	A kért mentés befejeződik; a megsemmisített store-ba később érkező írásokat figyelmen kívül hagyja.
`A tároló nem érhető el`	A store a memóriában fut, a status().available értéke false, a mentések pedig elutasulnak.
`Egy adapter megakad`	A művelet az operationTimeoutMs után időtúllépéssel véget ér, a későbbi munka pedig megvárja, amíg az adapter befejezi.
`Túl sok függő munka`	Az új műveletek korlátlan növekedés helyett QUEUE_FULL hibával elutasulnak.

Egy store műveletei soha nem fedik egymást. Egy mentés, amely akkor indul, amikor egy másik vár, a legújabb értéket veszi át, így a minden változáskor történő mentés a sor feltöltése nélkül írja ki az utolsó állapotot.

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

Próbálja ki

Lassítsa le a tárolót, tegye sikertelenné az írásokat, vagy távolítsa el teljesen a tárolót.

VezérlőNem része a példakódnak. Az értékek props-ként érkeznek a példába.

Késleltetéslatency
Sikertelen írásokfailWrites
A tároló nem érhető elunavailable

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

A példa előkészítése…

Az élő példákhoz JavaScript kell. Az alábbi kódot úgy olvashatja, ahogy van.

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) => [`Mentve: ${JSON.stringify(value)}`, ...list]),
      (reason) => setResults((list) => [`Sikertelen: ${reason.code ?? reason.message}`, ...list]),
    );

  return (
    <main>
      <label>
        Megjegyzés
        <input value={note} onChange={(event) => useNote.set(event.target.value)} />
      </label>
      <div className="actions">
        <button onClick={save}>Mentés</button>
        <button
          onClick={() => {
            save();
            save();
            save();
          }}
        >
          Mentés háromszor
        </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>Eredmények</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('A lemez megtelt');
    records.set(key, value);
  },
  async removeItem(key) {
    await wait();
    records.delete(key);
  },
};

Ha a betöltés sikertelen

A restateManager.ready BULK_OPERATION_FAILED hibával utasul el, és felsorol minden sikertelen store-t. Amíg az adott rekord be nem töltődik, az autoSave és a saveAll nem cseréli le, és LOAD_FAILED hibát jelez.

Próbálja újra az initialize() hívással, hogy megtartsa és elmentse a változásokat, hívja meg a restore() metódust az elvetésükhöz, vagy a save()-et a rekord szándékos felülírásához.

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

Mentés és bezárás

A leválasztás előtt kért mentés így is befejeződik, ezért a „Mentés és bezárás” kezelőnek nem kell várnia.

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

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

A tároló nem érhető el

A szerveroldali renderelés és a böngésző által letiltott tároló nem indítási hiba. Ellenőrizze az available mezőt, hogy jelezze a felhasználóknak: a változások csak a memóriában maradnak.

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

Mentett adatok ellenőrzése és migrálása

A version, a migrate és a validate megvédi a régi vagy sérült rekordoktól. A validate mentés előtt, valamint helyreállítás vagy migrálás után fut.

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

Saját tároló

Bármely objektum megfelel, amelynek van getItem, setItem és removeItem metódusa. A metódusok visszaadhatnak értéket vagy Promise-t; az isAvailable opcionális.

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

Korlátok és időtúllépések

Állítsa be, meddig tarthat egy művelet, hány várakozhat, és mekkora lehet egy érték.

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

Hibakódok

A restate által létrehozott hibák name mezője RestateError, van code mezőjük, mentett store-nál pedig key mezőjük is. A tárolóadapterek és az Ön callbackjei saját hibákkal is elutasíthatnak.

Kód	Jelentés
`BULK_OPERATION_FAILED`	Egy tömeges hívás, például a restateManager.ready vagy a saveAll, hibákba ütközött; lásd: error.failures.
`INDEXEDDB_ABORTED`	Egy IndexedDB-tranzakció megszakadt.
`INDEXEDDB_BLOCKED`	Az adatbázis megnyitását egy másik fülön lévő kapcsolat blokkolta.
`INDEXEDDB_CONNECTION_CLOSING`	Az adatbázis-kapcsolat éppen bezárult, amikor a kérés elindult.
`INDEXEDDB_OPEN_FAILED`	Az adatbázist nem sikerült megnyitni.
`INDEXEDDB_REQUEST_FAILED`	Egy IndexedDB-kérés sikertelen volt.
`INDEXEDDB_STORE_MISSING`	A már létező adatbázisból hiányzik az object store.
`INVALID_STORAGE_RECORD`	A mentett rekord nem érvényes restate-rekord.
`INVALID_STORED_VALUE`	Az érték nem ment át a validate ellenőrzésen.
`LIFECYCLE_LIMIT`	Egy updater újra és újra elindult és leállt.
`LOAD_FAILED`	A rekordot nem sikerült betölteni, ezért az automatikus vagy tömeges mentés nem cserélte le.
`MMKV_UNAVAILABLE`	A react-native-mmkv nem töltődött be.
`MULTIPLE_ERRORS`	Egy műveletben több callback is hibázott; lásd: error.errors.
`NOTIFICATION_LIMIT`	A megfigyelők körkörösen újabb és újabb változásokat ütemeztek.
`OBSERVER_ERROR`	Egy listener vagy életciklus-callback hibát dobott.
`OPERATION_ABORTED`	Egy tárolóművelet megszakadt.
`QUEUE_FULL`	Több művelet várakozott, mint amennyit a maxPendingOperations megenged.
`REENTRANT_SETTER`	Egy állapot-updater futás közben ugyanazt a store-t próbálta módosítani.
`SCOPE_DESTROYED`	Egy megsemmisített scope-pal próbáltak store-okat létrehozni.
`SEQUENCE_EXHAUSTED`	Egy belső sorozatból elfogytak az azonosítók.
`STORAGE_BLOCKED`	Egy korábbi adapterhívás időtúllépés vagy megszakítás után sem fejeződött be.
`STORAGE_TIMEOUT`	Egy művelet tovább tartott az operationTimeoutMs értéknél.
`STORAGE_UNAVAILABLE`	Itt nem használható tároló; a store tovább fut a memóriában.
`STORAGE_VALUE_TOO_LARGE`	A kódolt érték meghaladja a maxStorageCharacters értéket.
`STORAGE_VERSION_MISMATCH`	A rekord verziója eltér, és egyetlen migrate függvény sem kezeli.
`STORE_DESTROYED`	Egy megsemmisített store-ra iratkoztak fel, vagy tárolóhasználatot kértek tőle.

A restate 1.0 API-jához írva