restate / v1.0.0

Pålitelighet by design

Hva restate garanterer når lagringen er treg, svikter eller mangler, og hvordan du leser feilene den melder.

På denne siden

Garantiene Ordnede lagringer Prøv det Når innlastingen feiler Lagre og lukk Ingen lagring tilgjengelig Valider og migrer lagrede data Bruk din egen lagring Grenser og tidsavbrudd Feilkoder

Garantiene

Denne oppførselen er en del av 1.0-kontrakten og dekkes av pakkens tester.

Situasjon	Hva restate gjør
`Flere lagringer på rad`	Kjører dem i rekkefølge per store; en lagring i kø skriver den nyeste verdien.
`En post ble ikke lastet inn`	autoSave og masselagring hopper over den med LOAD_FAILED; bare et eksplisitt save() erstatter den.
`Komponenten avmonteres under en lagring`	Den forespurte lagringen fullføres; senere skrivinger til den ødelagte storen ignoreres.
`Lagringen er utilgjengelig`	Storen kjører i minnet, status().available er false, og lagringer avvises.
`En adapter henger`	Operasjonen får tidsavbrudd etter operationTimeoutMs, og senere arbeid venter til adapteren er ferdig.
`For mye ventende arbeid`	Nye operasjoner avvises med QUEUE_FULL i stedet for å vokse uten grense.

Ordnede lagringer

Operasjonene til én store overlapper aldri. En lagring som starter mens en annen venter, tar den nyeste verdien, så lagring ved hver endring skriver siste tilstand uten å fylle køen.

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øv det

Gjør lagringen tregere, la skrivinger feile eller fjern lagringen helt.

KontrollerIkke en del av eksempelkoden. Verdiene når eksempelet som props.

Forsinkelselatency
La skrivinger feilefailWrites
Lagring utilgjengeligunavailable

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

Forbereder eksempelet …

Live-eksempler krever JavaScript. Koden nedenfor kan leses som den er.

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

  return (
    <main>
      <label>
        Notat
        <input value={note} onChange={(event) => useNote.set(event.target.value)} />
      </label>
      <div className="actions">
        <button onClick={save}>Lagre</button>
        <button
          onClick={() => {
            save();
            save();
            save();
          }}
        >
          Lagre tre ganger
        </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>Resultater</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('Disken er full');
    records.set(key, value);
  },
  async removeItem(key) {
    await wait();
    records.delete(key);
  },
};

Når innlastingen feiler

restateManager.ready avvises med BULK_OPERATION_FAILED og lister opp hver store som feilet. Til den posten lastes inn, erstatter ikke autoSave og saveAll den, og de melder LOAD_FAILED.

Prøv igjen med initialize() for å beholde endringene og lagre dem, kall restore() for å forkaste dem, eller save() for å overskrive posten med vilje.

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

Lagre og lukk

En lagring som ble bedt om før unmount, fullføres likevel, så en håndterer for «Lagre og lukk» trenger ikke vente.

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

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

Ingen lagring tilgjengelig

Serverrendering og lagring som nettleseren blokkerer, er ikke oppstartsfeil. Sjekk available for å fortelle brukerne at endringene bare finnes i minnet.

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

Valider og migrer lagrede data

version, migrate og validate beskytter deg mot gamle eller ødelagte poster. validate kjøres før lagring og etter gjenoppretting eller migrering.

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

Bruk din egen lagring

Ethvert objekt med getItem, setItem og removeItem fungerer. Metodene kan returnere verdier eller Promise; isAvailable er valgfri.

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

Grenser og tidsavbrudd

Juster hvor lenge en operasjon kan ta, hvor mange som kan vente, og hvor stor en verdi kan være.

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

Feilkoder

Feil som restate oppretter, har name RestateError, en code og, for lagrede stores, key. Lagringsadaptere og dine egne callbacks kan avvise med egne feil.

Kode	Betydning
`BULK_OPERATION_FAILED`	Et massekall som restateManager.ready eller saveAll hadde feil; se error.failures.
`INDEXEDDB_ABORTED`	En IndexedDB-transaksjon ble avbrutt.
`INDEXEDDB_BLOCKED`	Åpningen av databasen ble blokkert av en tilkobling i en annen fane.
`INDEXEDDB_CONNECTION_CLOSING`	Databasetilkoblingen holdt på å lukkes da forespørselen startet.
`INDEXEDDB_OPEN_FAILED`	Databasen kunne ikke åpnes.
`INDEXEDDB_REQUEST_FAILED`	En IndexedDB-forespørsel mislyktes.
`INDEXEDDB_STORE_MISSING`	Object store mangler i en allerede opprettet database.
`INVALID_STORAGE_RECORD`	En lagret post er ikke en gyldig restate-post.
`INVALID_STORED_VALUE`	En verdi besto ikke validate.
`LIFECYCLE_LIMIT`	En updater fortsatte å starte og stoppe.
`LOAD_FAILED`	En post kunne ikke lastes inn, så en automatisk lagring eller masselagring erstattet den ikke.
`MMKV_UNAVAILABLE`	react-native-mmkv kunne ikke lastes inn.
`MULTIPLE_ERRORS`	Flere callbacks feilet i én operasjon; se error.errors.
`NOTIFICATION_LIMIT`	Observatører fortsatte å planlegge endringer i en løkke.
`OBSERVER_ERROR`	En lytter eller livssyklus-callback kastet en feil.
`OPERATION_ABORTED`	En lagringsoperasjon ble avbrutt.
`QUEUE_FULL`	Flere operasjoner ventet enn maxPendingOperations tillater.
`REENTRANT_SETTER`	En state-updater prøvde å endre den samme storen mens den kjørte.
`SCOPE_DESTROYED`	Et ødelagt scope ble brukt til å opprette stores.
`SEQUENCE_EXHAUSTED`	En intern sekvens gikk tom for id-er.
`STORAGE_BLOCKED`	Et tidligere adapterkall ble ikke fullført etter tidsavbrudd eller avbrytelse.
`STORAGE_TIMEOUT`	En operasjon tok lengre tid enn operationTimeoutMs.
`STORAGE_UNAVAILABLE`	Lagring kan ikke brukes her; storen fortsetter i minnet.
`STORAGE_VALUE_TOO_LARGE`	Den kodede verdien overskrider maxStorageCharacters.
`STORAGE_VERSION_MISMATCH`	En post har en annen versjon, og ingen migrate-funksjon håndterer den.
`STORE_DESTROYED`	Noen abonnerte på en ødelagt store eller ba den bruke lagring.

Skrevet for API-et i restate 1.0