restate / v1.0.0

Luotettava suunnittelultaan

Mitä restate takaa, kun tallennustila on hidas, pettää tai puuttuu, ja miten sen raportoimia virheitä luetaan.

Tällä sivulla

Takuut Tallennukset järjestyksessä Kokeile Kun lataus epäonnistuu Tallenna ja sulje Tallennustila ei ole käytettävissä Tallennettujen tietojen validointi ja siirto Oma tallennustila Rajat ja aikakatkaisut Virhekoodit

Takuut

Tämä toiminta on osa 1.0-sopimusta, ja paketin testit kattavat sen.

Tilanne	Mitä restate tekee
`Useita tallennuksia peräkkäin`	Suorittaa ne järjestyksessä storekohtaisesti; jonossa oleva tallennus kirjoittaa uusimman arvon.
`Tietue ei latautunut`	autoSave ja joukkotallennukset ohittavat sen virheellä LOAD_FAILED; vain nimenomainen save() korvaa sen.
`Komponentti irrotetaan tallennuksen aikana`	Pyydetty tallennus valmistuu; myöhemmät kirjoitukset tuhottuun storeen ohitetaan.
`Tallennustila ei ole käytettävissä`	Store toimii muistissa, status().available on false ja tallennukset hylätään.
`Sovitin jumittuu`	Toiminto aikakatkaistaan operationTimeoutMs-ajan jälkeen, ja myöhempi työ odottaa sovittimen valmistumista.
`Liikaa odottavaa työtä`	Uudet toiminnot hylätään virheellä QUEUE_FULL sen sijaan, että jono kasvaisi rajatta.

Yhden storen toiminnot eivät koskaan mene päällekkäin. Tallennus, joka alkaa toisen odottaessa, ottaa uusimman arvon, joten jokaisella muutoksella tallentaminen kirjoittaa viimeisen tilan täyttämättä jonoa.

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

Kokeile

Hidasta tallennustilaa, saa kirjoitukset epäonnistumaan tai poista tallennustila kokonaan.

OhjainEi osa esimerkkikoodia. Arvot tulevat esimerkille props-muodossa.

Viivelatency
Epäonnistuvat kirjoituksetfailWrites
Tallennustila ei käytettävissäunavailable

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

Valmistellaan esimerkkiä…

Live-esimerkit tarvitsevat JavaScriptiä. Voit lukea alla olevan koodin sellaisenaan.

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

  return (
    <main>
      <label>
        Huomautus
        <input value={note} onChange={(event) => useNote.set(event.target.value)} />
      </label>
      <div className="actions">
        <button onClick={save}>Tallenna</button>
        <button
          onClick={() => {
            save();
            save();
            save();
          }}
        >
          Tallenna kolme kertaa
        </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>Tulokset</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('Levy on täynnä');
    records.set(key, value);
  },
  async removeItem(key) {
    await wait();
    records.delete(key);
  },
};

Kun lataus epäonnistuu

restateManager.ready hylätään virheellä BULK_OPERATION_FAILED, ja se luettelee jokaisen epäonnistuneen storen. Kunnes kyseinen tietue latautuu, autoSave ja saveAll eivät korvaa sitä vaan raportoivat LOAD_FAILED.

Yritä uudelleen initialize()-kutsulla säilyttääksesi muutokset ja tallentaaksesi ne, kutsu restore() hylätäksesi ne tai save() korvataksesi tietueen tarkoituksella.

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

Tallenna ja sulje

Ennen irrottamista pyydetty tallennus valmistuu silti, joten ”Tallenna ja sulje” -käsittelijän ei tarvitse odottaa.

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

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

Tallennustila ei ole käytettävissä

Palvelinrenderöinti ja selaimen estämä tallennustila eivät ole käynnistysvirheitä. Tarkista available kertoaksesi käyttäjille, että muutokset ovat vain muistissa.

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

Tallennettujen tietojen validointi ja siirto

version, migrate ja validate suojaavat vanhoilta tai vioittuneilta tietueilta. validate suoritetaan ennen tallennusta sekä palautuksen tai siirron jälkeen.

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

Oma tallennustila

Mikä tahansa objekti, jolla on getItem, setItem ja removeItem, kelpaa. Metodit voivat palauttaa arvoja tai Promiseja; isAvailable on valinnainen.

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

Rajat ja aikakatkaisut

Määritä, kuinka kauan toiminto saa kestää, kuinka moni saa odottaa ja kuinka suuri arvo saa olla.

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

Virhekoodit

restaten luomien virheiden name on RestateError, niillä on code ja tallennetuissa storeissa key. Tallennussovittimet ja omat callbackisi voivat hylätä omilla virheillään.

Koodi	Merkitys
`BULK_OPERATION_FAILED`	Joukkokutsussa, kuten restateManager.ready tai saveAll, oli epäonnistumisia; katso error.failures.
`INDEXEDDB_ABORTED`	IndexedDB-transaktio keskeytettiin.
`INDEXEDDB_BLOCKED`	Toisen välilehden yhteys esti tietokannan avaamisen.
`INDEXEDDB_CONNECTION_CLOSING`	Tietokantayhteys oli sulkeutumassa pyynnön alkaessa.
`INDEXEDDB_OPEN_FAILED`	Tietokantaa ei voitu avata.
`INDEXEDDB_REQUEST_FAILED`	IndexedDB-pyyntö epäonnistui.
`INDEXEDDB_STORE_MISSING`	Jo olemassa olevasta tietokannasta puuttuu object store.
`INVALID_STORAGE_RECORD`	Tallennettu tietue ei ole kelvollinen restate-tietue.
`INVALID_STORED_VALUE`	Arvo ei läpäissyt validate-tarkistusta.
`LIFECYCLE_LIMIT`	Updater käynnistyi ja pysähtyi toistuvasti.
`LOAD_FAILED`	Tietuetta ei voitu ladata, joten automaattinen tai joukkotallennus ei korvannut sitä.
`MMKV_UNAVAILABLE`	react-native-mmkv-pakettia ei voitu ladata.
`MULTIPLE_ERRORS`	Useat callbackit epäonnistuivat yhdessä toiminnossa; katso error.errors.
`NOTIFICATION_LIMIT`	Tarkkailijat ajoittivat jatkuvasti muutoksia silmukassa.
`OBSERVER_ERROR`	Listener tai elinkaaren callback heitti virheen.
`OPERATION_ABORTED`	Tallennustoiminto peruttiin.
`QUEUE_FULL`	Odottavia toimintoja oli enemmän kuin maxPendingOperations sallii.
`REENTRANT_SETTER`	Tilan updater yritti muuttaa samaa storea kesken suorituksensa.
`SCOPE_DESTROYED`	Tuhottua scopea käytettiin storejen luomiseen.
`SEQUENCE_EXHAUSTED`	Sisäisestä sarjasta loppuivat tunnisteet.
`STORAGE_BLOCKED`	Aiempi sovitinkutsu ei päättynyt aikakatkaisun tai perumisen jälkeen.
`STORAGE_TIMEOUT`	Toiminto kesti kauemmin kuin operationTimeoutMs.
`STORAGE_UNAVAILABLE`	Tallennustilaa ei voi käyttää tässä; store toimii edelleen muistissa.
`STORAGE_VALUE_TOO_LARGE`	Koodattu arvo ylittää maxStorageCharacters-rajan.
`STORAGE_VERSION_MISMATCH`	Tietueella on eri versio, eikä mikään migrate-funktio käsittele sitä.
`STORE_DESTROYED`	Tuhottua storea tilattiin tai siltä pyydettiin tallennustilan käyttöä.

Kirjoitettu restate 1.0 -rajapinnalle (API)