restate / v1.0.0

Pouzdanost by design

Što restate jamči kad je spremište sporo, zakaže ili nedostaje i kako čitati pogreške koje javlja.

Na ovoj stranici

Jamstva Spremanja redom Isprobajte Kad učitavanje ne uspije Spremi i zatvori Nema dostupnog spremišta Validacija i migracija spremljenih podataka Vlastito spremište Ograničenja i vremenska ograničenja Kodovi pogrešaka

Jamstva

Ovo ponašanje dio je ugovora 1.0 i pokrivaju ga testovi paketa.

Situacija	Što restate radi
`Više spremanja zaredom`	Izvodi ih redom za svaki store; spremanje u redu zapisuje najnoviju vrijednost.
`Zapis se nije učitao`	autoSave i skupna spremanja preskaču ga uz LOAD_FAILED; zamjenjuje ga samo izričiti save().
`Komponenta se demontira tijekom spremanja`	Zatraženo spremanje se dovršava; kasniji zapisi u uništeni store zanemaruju se.
`Spremište nije dostupno`	Store radi u memoriji, status().available je false, a spremanja se odbijaju.
`Adapter zapne`	Operaciji istječe vrijeme nakon operationTimeoutMs, a kasniji posao čeka dok adapter ne završi.
`Previše posla na čekanju`	Nove operacije odbijaju se s QUEUE_FULL umjesto da rastu bez ograničenja.

Spremanja redom

Operacije jednog storea nikad se ne preklapaju. Spremanje pokrenuto dok drugo čeka uzima najnoviju vrijednost, pa spremanje pri svakoj promjeni zapisuje posljednje stanje bez punjenja reda.

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

Isprobajte

Usporite spremište, neka zapisi ne uspiju ili potpuno uklonite spremište.

KontrolerNije dio koda primjera. Vrijednosti stižu u primjer kao props.

Kašnjenjelatency
Neuspjeli zapisifailWrites
Spremište nedostupnounavailable

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

Priprema primjera…

Primjeri uživo trebaju JavaScript. Kod ispod možete čitati takav kakav jest.

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

  return (
    <main>
      <label>
        Bilješka
        <input value={note} onChange={(event) => useNote.set(event.target.value)} />
      </label>
      <div className="actions">
        <button onClick={save}>Spremi</button>
        <button
          onClick={() => {
            save();
            save();
            save();
          }}
        >
          Spremi tri puta
        </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>Rezultati</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('Disk je pun');
    records.set(key, value);
  },
  async removeItem(key) {
    await wait();
    records.delete(key);
  },
};

Kad učitavanje ne uspije

restateManager.ready odbija se s BULK_OPERATION_FAILED i navodi svaki store koji nije uspio. Dok se taj zapis ne učita, autoSave i saveAll ga ne zamjenjuju i javljaju LOAD_FAILED.

Pokušajte ponovno s initialize() da biste zadržali izmjene i spremili ih, pozovite restore() da ih odbacite ili save() da namjerno prepišete zapis.

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

Spremi i zatvori

Spremanje zatraženo prije demontiranja ipak se dovršava, pa rukovatelj za „Spremi i zatvori” ne mora čekati.

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

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

Nema dostupnog spremišta

Renderiranje na poslužitelju i spremište koje preglednik blokira nisu pogreške pri pokretanju. Provjeravajte available da biste korisnicima rekli da izmjene ostaju samo u memoriji.

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

Validacija i migracija spremljenih podataka

version, migrate i validate štite vas od starih ili oštećenih zapisa. validate se pokreće prije spremanja i nakon vraćanja ili migracije.

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

Vlastito spremište

Poslužit će bilo koji objekt s getItem, setItem i removeItem. Metode mogu vraćati vrijednosti ili Promise; isAvailable nije obavezan.

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

Ograničenja i vremenska ograničenja

Podesite koliko dugo operacija smije trajati, koliko ih smije čekati i koliko velika smije biti vrijednost.

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

Kodovi pogrešaka

Pogreške koje stvara restate imaju name RestateError, code i, kod spremljenih storeova, key. Adapteri spremišta i vaši callbackovi mogu odbiti vlastitim pogreškama.

Kod	Značenje
`BULK_OPERATION_FAILED`	Skupni poziv poput restateManager.ready ili saveAll imao je pogreške; vidi error.failures.
`INDEXEDDB_ABORTED`	Transakcija IndexedDB je prekinuta.
`INDEXEDDB_BLOCKED`	Otvaranje baze podataka blokirala je veza u drugoj kartici.
`INDEXEDDB_CONNECTION_CLOSING`	Veza s bazom podataka zatvarala se kad je zahtjev počeo.
`INDEXEDDB_OPEN_FAILED`	Baza podataka nije se mogla otvoriti.
`INDEXEDDB_REQUEST_FAILED`	Zahtjev IndexedDB nije uspio.
`INDEXEDDB_STORE_MISSING`	U već stvorenoj bazi podataka nedostaje object store.
`INVALID_STORAGE_RECORD`	Spremljeni zapis nije valjan restate zapis.
`INVALID_STORED_VALUE`	Vrijednost nije prošla validate.
`LIFECYCLE_LIMIT`	Updater se stalno pokretao i zaustavljao.
`LOAD_FAILED`	Zapis se nije mogao učitati, pa ga automatsko ni skupno spremanje nije zamijenilo.
`MMKV_UNAVAILABLE`	react-native-mmkv nije se mogao učitati.
`MULTIPLE_ERRORS`	U jednoj operaciji nije uspjelo više callbackova; vidi error.errors.
`NOTIFICATION_LIMIT`	Promatrači su u petlji stalno zakazivali promjene.
`OBSERVER_ERROR`	Slušatelj ili callback životnog ciklusa bacio je pogrešku.
`OPERATION_ABORTED`	Operacija sa spremištem je otkazana.
`QUEUE_FULL`	Čekalo je više operacija nego što dopušta maxPendingOperations.
`REENTRANT_SETTER`	Updater stanja pokušao je promijeniti isti store dok se izvodio.
`SCOPE_DESTROYED`	Za stvaranje storeova korišten je uništeni scope.
`SEQUENCE_EXHAUSTED`	Unutarnjem nizu ponestalo je identifikatora.
`STORAGE_BLOCKED`	Prethodni poziv adaptera nije završio nakon isteka vremena ili otkazivanja.
`STORAGE_TIMEOUT`	Operacija je trajala dulje od operationTimeoutMs.
`STORAGE_UNAVAILABLE`	Spremište se ovdje ne može koristiti; store i dalje radi u memoriji.
`STORAGE_VALUE_TOO_LARGE`	Kodirana vrijednost premašuje maxStorageCharacters.
`STORAGE_VERSION_MISMATCH`	Zapis ima drugu verziju i nijedna funkcija migrate je ne obrađuje.
`STORE_DESTROYED`	Došlo je do pretplate na uništeni store ili je od njega zatraženo korištenje spremišta.

Napisano za API restate 1.0