restate / v1.0.0

Betrouwbaarheid by design

Wat restate garandeert als opslag traag is, faalt of ontbreekt, en hoe je de gemelde fouten leest.

Op deze pagina

De garanties Saves op volgorde Probeer het Als laden mislukt Opslaan en sluiten Geen opslag beschikbaar Opgeslagen data valideren en migreren Je eigen opslag gebruiken Limieten en time-outs Foutcodes

De garanties

Dit gedrag hoort bij het contract van 1.0 en wordt gedekt door de tests van het pakket.

Situatie	Wat restate doet
`Meerdere saves achter elkaar`	Voert ze per store op volgorde uit; een save in de wachtrij schrijft de nieuwste waarde.
`Een record laadde niet`	autoSave en bulksaves slaan het over met LOAD_FAILED; alleen een expliciete save() vervangt het.
`Het component unmount tijdens een save`	De aangevraagde save wordt afgemaakt; latere schrijfacties naar de vernietigde store worden genegeerd.
`Opslag is niet beschikbaar`	De store werkt in het geheugen, status().available is false en saves worden geweigerd.
`Een adapter loopt vast`	De bewerking verloopt na operationTimeoutMs en later werk wacht tot de adapter klaar is.
`Te veel werk in de wachtrij`	Nieuwe bewerkingen worden geweigerd met QUEUE_FULL in plaats van onbeperkt te groeien.

Bewerkingen van één store overlappen nooit. Een save die start terwijl een andere wacht, neemt de nieuwste waarde, dus opslaan bij elke wijziging schrijft de laatste state zonder de wachtrij te vullen.

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

Probeer het

Maak de opslag trager, laat schrijfacties mislukken of haal de opslag helemaal weg.

ControllerGeen onderdeel van de voorbeeldcode. Waarden komen als props in het voorbeeld.

Vertraginglatency
Schrijfacties laten mislukkenfailWrites
Opslag niet beschikbaarunavailable

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

Voorbeeld voorbereiden…

Live voorbeelden hebben JavaScript nodig. De code hieronder is gewoon te lezen.

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

  return (
    <main>
      <label>
        Notitie
        <input value={note} onChange={(event) => useNote.set(event.target.value)} />
      </label>
      <div className="actions">
        <button onClick={save}>Opslaan</button>
        <button
          onClick={() => {
            save();
            save();
            save();
          }}
        >
          Drie keer opslaan
        </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>Resultaten</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('De schijf is vol');
    records.set(key, value);
  },
  async removeItem(key) {
    await wait();
    records.delete(key);
  },
};

Als laden mislukt

restateManager.ready wordt geweigerd met BULK_OPERATION_FAILED en noemt elke mislukte store. Totdat dat record laadt, vervangen autoSave en saveAll het niet en melden ze LOAD_FAILED.

Probeer opnieuw met initialize() om bewerkingen te houden en op te slaan, roep restore() aan om ze te verwerpen, of save() om het record bewust te overschrijven.

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

Opslaan en sluiten

Een save die vóór de unmount is aangevraagd, wordt toch afgemaakt, dus een handler voor „Opslaan en sluiten” hoeft niet te wachten.

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

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

Geen opslag beschikbaar

Server-rendering en door de browser geblokkeerde opslag zijn geen opstartfouten. Controleer available om gebruikers te vertellen dat bewerkingen alleen in het geheugen blijven.

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

Opgeslagen data valideren en migreren

version, migrate en validate beschermen je tegen oude of beschadigde records. validate draait vóór het opslaan en na terugzetten of migreren.

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

Je eigen opslag gebruiken

Elk object met getItem, setItem en removeItem werkt. De methoden mogen waarden of een Promise teruggeven; isAvailable is optioneel.

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

Limieten en time-outs

Stel in hoe lang een bewerking mag duren, hoeveel er mogen wachten en hoe groot een waarde mag zijn.

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

Foutcodes

Fouten die restate aanmaakt hebben name RestateError, een code en, bij opgeslagen stores, key. Opslagadapters en je eigen callbacks kunnen weigeren met eigen fouten.

Code	Betekenis
`BULK_OPERATION_FAILED`	Een bulkaanroep zoals restateManager.ready of saveAll had fouten; zie error.failures.
`INDEXEDDB_ABORTED`	Een IndexedDB-transactie is afgebroken.
`INDEXEDDB_BLOCKED`	Het openen van de database werd geblokkeerd door een verbinding in een ander tabblad.
`INDEXEDDB_CONNECTION_CLOSING`	De databaseverbinding werd gesloten toen het verzoek begon.
`INDEXEDDB_OPEN_FAILED`	De database kon niet worden geopend.
`INDEXEDDB_REQUEST_FAILED`	Een IndexedDB-verzoek is mislukt.
`INDEXEDDB_STORE_MISSING`	De object store ontbreekt in een al aangemaakte database.
`INVALID_STORAGE_RECORD`	Een opgeslagen record is geen geldig restate-record.
`INVALID_STORED_VALUE`	Een waarde kwam niet door validate.
`LIFECYCLE_LIMIT`	Een updater bleef starten en stoppen.
`LOAD_FAILED`	Een record kon niet laden, dus een automatische of bulksave heeft het niet vervangen.
`MMKV_UNAVAILABLE`	react-native-mmkv kon niet worden geladen.
`MULTIPLE_ERRORS`	Meerdere callbacks mislukten in één bewerking; zie error.errors.
`NOTIFICATION_LIMIT`	Observers bleven in een lus wijzigingen inplannen.
`OBSERVER_ERROR`	Een listener of lifecycle-callback gooide een fout.
`OPERATION_ABORTED`	Een opslagbewerking is afgebroken.
`QUEUE_FULL`	Er wachtten meer bewerkingen dan maxPendingOperations toestaat.
`REENTRANT_SETTER`	Een state-updater probeerde dezelfde store te wijzigen terwijl hij draaide.
`SCOPE_DESTROYED`	Een vernietigde scope werd gebruikt om stores aan te maken.
`SEQUENCE_EXHAUSTED`	Een interne reeks had geen id's meer.
`STORAGE_BLOCKED`	Een eerdere adapteraanroep werd na een time-out of afbreking niet afgerond.
`STORAGE_TIMEOUT`	Een bewerking duurde langer dan operationTimeoutMs.
`STORAGE_UNAVAILABLE`	Opslag kan hier niet worden gebruikt; de store blijft in het geheugen werken.
`STORAGE_VALUE_TOO_LARGE`	De gecodeerde waarde overschrijdt maxStorageCharacters.
`STORAGE_VERSION_MISMATCH`	Een record heeft een andere versie en geen migrate-functie die het afhandelt.
`STORE_DESTROYED`	Er werd geabonneerd op een vernietigde store of die werd gevraagd opslag te gebruiken.

Geschreven voor de API van restate 1.0