restate / v1.0.0

Tillförlitlighet by design

Vad restate garanterar när lagringen är långsam, fallerar eller saknas, och hur du läser felen den rapporterar.

På den här sidan

Garantierna Ordnade sparningar Prova När inläsningen misslyckas Spara och stäng Ingen lagring tillgänglig Validera och migrera sparad data Använd din egen lagring Gränser och timeouts Felkoder

Garantierna

De här beteendena ingår i 1.0-kontraktet och täcks av paketets tester.

Situation	Vad restate gör
`Flera sparningar i rad`	Kör dem i ordning per store; en köad sparning skriver det senaste värdet.
`En post lästes inte in`	autoSave och massparningar hoppar över den med LOAD_FAILED; bara ett explicit save() ersätter den.
`Komponenten avmonteras under en sparning`	Den begärda sparningen slutförs; senare skrivningar till den förstörda storen ignoreras.
`Lagringen är otillgänglig`	Storen fungerar i minnet, status().available är false och sparningar avvisas.
`En adapter hänger sig`	Åtgärden får timeout efter operationTimeoutMs och senare arbete väntar tills adaptern är klar.
`För mycket väntande arbete`	Nya åtgärder avvisas med QUEUE_FULL i stället för att växa utan gräns.

Ordnade sparningar

En stores åtgärder överlappar aldrig. En sparning som startar medan en annan väntar tar det nyaste värdet, så att spara vid varje ändring skriver det senaste tillståndet utan att fylla kön.

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

Prova

Gör lagringen långsammare, låt skrivningar misslyckas eller ta bort lagringen helt.

KontrollerInte en del av exempelkoden. Värdena når exemplet som props.

Fördröjninglatency
Låt skrivningar misslyckasfailWrites
Lagring otillgängligunavailable

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

Förbereder exemplet…

Liveexempel kräver JavaScript. Koden nedan går att läsa som den är.

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

  return (
    <main>
      <label>
        Anteckning
        <input value={note} onChange={(event) => useNote.set(event.target.value)} />
      </label>
      <div className="actions">
        <button onClick={save}>Spara</button>
        <button
          onClick={() => {
            save();
            save();
            save();
          }}
        >
          Spara tre gånger
        </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>Resultat</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 är full');
    records.set(key, value);
  },
  async removeItem(key) {
    await wait();
    records.delete(key);
  },
};

När inläsningen misslyckas

restateManager.ready avvisas med BULK_OPERATION_FAILED och listar varje store som misslyckades. Tills den posten läses in ersätter autoSave och saveAll den inte och rapporterar LOAD_FAILED.

Försök igen med initialize() för att behålla ändringarna och spara dem, anropa restore() för att kasta dem eller save() för att medvetet skriva över posten.

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

Spara och stäng

En sparning som begärts före unmount slutförs ändå, så en hanterare för ”Spara och stäng” behöver inte vänta.

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

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

Ingen lagring tillgänglig

Serverrendering och lagring som webbläsaren blockerar är inga startfel. Kontrollera available för att berätta för användarna att ändringarna bara finns 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.');
}

Validera och migrera sparad data

version, migrate och validate skyddar dig mot gamla eller trasiga poster. validate körs före sparning och efter återställning 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),
  },
);

Använd din egen lagring

Vilket objekt som helst med getItem, setItem och removeItem fungerar. Metoderna kan returnera värden eller Promise; isAvailable är valfri.

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

Gränser och timeouts

Justera hur länge en åtgärd får ta, hur många som får vänta och hur stort ett värde får vara.

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

Felkoder

Fel som restate skapar har name RestateError, en code och, för sparade stores, key. Lagringsadaptrar och dina egna callbacks kan avvisa med egna fel.

Kod	Betydelse
`BULK_OPERATION_FAILED`	Ett massanrop som restateManager.ready eller saveAll hade fel; se error.failures.
`INDEXEDDB_ABORTED`	En IndexedDB-transaktion avbröts.
`INDEXEDDB_BLOCKED`	Att öppna databasen blockerades av en anslutning i en annan flik.
`INDEXEDDB_CONNECTION_CLOSING`	Databasanslutningen höll på att stängas när begäran startade.
`INDEXEDDB_OPEN_FAILED`	Databasen kunde inte öppnas.
`INDEXEDDB_REQUEST_FAILED`	En IndexedDB-begäran misslyckades.
`INDEXEDDB_STORE_MISSING`	Object store saknas i en redan skapad databas.
`INVALID_STORAGE_RECORD`	En sparad post är inte en giltig restate-post.
`INVALID_STORED_VALUE`	Ett värde klarade inte validate.
`LIFECYCLE_LIMIT`	En updater fortsatte att starta och stoppa.
`LOAD_FAILED`	En post kunde inte läsas in, så en automatisk eller massparning ersatte den inte.
`MMKV_UNAVAILABLE`	react-native-mmkv kunde inte läsas in.
`MULTIPLE_ERRORS`	Flera callbacks misslyckades i en åtgärd; se error.errors.
`NOTIFICATION_LIMIT`	Observatörer fortsatte att schemalägga ändringar i en loop.
`OBSERVER_ERROR`	En lyssnare eller livscykel-callback kastade ett fel.
`OPERATION_ABORTED`	En lagringsåtgärd avbröts.
`QUEUE_FULL`	Fler åtgärder väntade än maxPendingOperations tillåter.
`REENTRANT_SETTER`	En state-updater försökte ändra samma store medan den kördes.
`SCOPE_DESTROYED`	Ett förstört scope användes för att skapa stores.
`SEQUENCE_EXHAUSTED`	En intern sekvens fick slut på id:n.
`STORAGE_BLOCKED`	Ett tidigare adapteranrop slutfördes inte efter timeout eller avbrott.
`STORAGE_TIMEOUT`	En åtgärd tog längre tid än operationTimeoutMs.
`STORAGE_UNAVAILABLE`	Lagring kan inte användas här; storen fortsätter att fungera i minnet.
`STORAGE_VALUE_TOO_LARGE`	Det kodade värdet överskrider maxStorageCharacters.
`STORAGE_VERSION_MISMATCH`	En post har en annan version och ingen migrate-funktion hanterar den.
`STORE_DESTROYED`	En förstörd store prenumererades på eller ombads använda lagring.

Skrivet för API:t i restate 1.0