restate / v1.0.0

Affidabilità by design

Che cosa garantisce restate quando l’archivio è lento, fallisce o manca, e come leggere gli errori che segnala.

In questa pagina

Le garanzie Salvataggi ordinati Provalo Quando il caricamento fallisce Salva e chiudi Nessun archivio disponibile Valida e migra i dati salvati Usa il tuo archivio Limiti e timeout Codici di errore

Le garanzie

Questi comportamenti fanno parte del contratto della 1.0 e sono coperti dai test del pacchetto.

Situazione	Che cosa fa restate
`Più salvataggi di fila`	Li esegue in ordine per ogni store; un salvataggio in coda scrive il valore più recente.
`Un record non si è caricato`	autoSave e i salvataggi in blocco lo saltano con LOAD_FAILED; solo un save() esplicito lo sostituisce.
`Il componente viene smontato durante un salvataggio`	Il salvataggio richiesto termina; le scritture successive nello store distrutto vengono ignorate.
`L’archivio non è disponibile`	Lo store funziona in memoria, status().available è false, i salvataggi vengono rifiutati.
`Un adattatore si blocca`	L’operazione va in timeout dopo operationTimeoutMs e il lavoro successivo aspetta che l’adattatore finisca.
`Troppo lavoro in sospeso`	Le nuove operazioni vengono rifiutate con QUEUE_FULL invece di crescere senza limiti.

Le operazioni di uno store non si sovrappongono mai. Un salvataggio avviato mentre un altro aspetta prende il valore più nuovo, così salvare a ogni modifica scrive l’ultimo stato senza riempire la coda.

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

Provalo

Rallenta l’archivio, fai fallire le scritture o rimuovi del tutto l’archivio.

ControllerNon fa parte del codice dell’esempio. I valori arrivano all’esempio come props.

Latenzalatency
Fai fallire le scritturefailWrites
Archivio non disponibileunavailable

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

Preparazione dell’esempio…

Gli esempi dal vivo richiedono JavaScript. Il codice qui sotto si legge così com’è.

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

  return (
    <main>
      <label>
        Nota
        <input value={note} onChange={(event) => useNote.set(event.target.value)} />
      </label>
      <div className="actions">
        <button onClick={save}>Salva</button>
        <button
          onClick={() => {
            save();
            save();
            save();
          }}
        >
          Salva tre volte
        </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>Risultati</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('Il disco è pieno');
    records.set(key, value);
  },
  async removeItem(key) {
    await wait();
    records.delete(key);
  },
};

Quando il caricamento fallisce

restateManager.ready viene rifiutato con BULK_OPERATION_FAILED ed elenca ogni store fallito. Finché quel record non si carica, autoSave e saveAll non lo sostituiscono e segnalano LOAD_FAILED.

Riprova con initialize() per tenere le modifiche e salvarle, chiama restore() per scartarle o save() per sovrascrivere il record di proposito.

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

Salva e chiudi

Un salvataggio richiesto prima dello smontaggio termina comunque, quindi un handler «Salva e chiudi» non deve aspettare.

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

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

Nessun archivio disponibile

Il rendering sul server e l’archivio bloccato dal browser non sono errori all’avvio. Controlla available per dire agli utenti che le modifiche restano solo in memoria.

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

Valida e migra i dati salvati

version, migrate e validate ti proteggono da record vecchi o corrotti. validate viene eseguito prima del salvataggio e dopo il ripristino o la migrazione.

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

Usa il tuo archivio

Va bene qualsiasi oggetto con getItem, setItem e removeItem. I metodi possono restituire valori o Promise; isAvailable è opzionale.

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

Limiti e timeout

Regola quanto può durare un’operazione, quante possono aspettare e quanto può essere grande un valore.

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

Codici di errore

Gli errori creati da restate hanno name RestateError, un code e, per gli store salvati, key. Gli adattatori di archiviazione e i tuoi callback possono rifiutare con errori propri.

Codice	Significato
`BULK_OPERATION_FAILED`	Una chiamata in blocco come restateManager.ready o saveAll ha avuto errori; vedi error.failures.
`INDEXEDDB_ABORTED`	Una transazione IndexedDB è stata annullata.
`INDEXEDDB_BLOCKED`	L’apertura del database è stata bloccata da una connessione in un’altra tab.
`INDEXEDDB_CONNECTION_CLOSING`	La connessione al database si stava chiudendo quando è iniziata la richiesta.
`INDEXEDDB_OPEN_FAILED`	Impossibile aprire il database.
`INDEXEDDB_REQUEST_FAILED`	Una richiesta IndexedDB non è riuscita.
`INDEXEDDB_STORE_MISSING`	L’object store non esiste in un database già creato.
`INVALID_STORAGE_RECORD`	Un record salvato non è un record restate valido.
`INVALID_STORED_VALUE`	Un valore non ha superato validate.
`LIFECYCLE_LIMIT`	Un updater continuava ad avviarsi e fermarsi.
`LOAD_FAILED`	Un record non si è potuto caricare, quindi un salvataggio automatico o in blocco non l’ha sostituito.
`MMKV_UNAVAILABLE`	Impossibile caricare react-native-mmkv.
`MULTIPLE_ERRORS`	Più callback sono falliti in un’operazione; vedi error.errors.
`NOTIFICATION_LIMIT`	Gli osservatori continuavano a programmare modifiche in un ciclo.
`OBSERVER_ERROR`	Un listener o un callback del ciclo di vita ha lanciato un errore.
`OPERATION_ABORTED`	Un’operazione di archiviazione è stata annullata.
`QUEUE_FULL`	In attesa c’erano più operazioni di quante ne consenta maxPendingOperations.
`REENTRANT_SETTER`	Un updater di stato ha provato a cambiare lo stesso store mentre era in esecuzione.
`SCOPE_DESTROYED`	È stato usato uno scope distrutto per creare store.
`SEQUENCE_EXHAUSTED`	Una sequenza interna ha esaurito gli identificatori.
`STORAGE_BLOCKED`	Una chiamata precedente all’adattatore non si è conclusa dopo un timeout o un annullamento.
`STORAGE_TIMEOUT`	Un’operazione ha impiegato più di operationTimeoutMs.
`STORAGE_UNAVAILABLE`	Qui l’archivio non può essere usato; lo store continua a funzionare in memoria.
`STORAGE_VALUE_TOO_LARGE`	Il valore codificato supera maxStorageCharacters.
`STORAGE_VERSION_MISMATCH`	Un record ha un’altra versione e nessuna funzione migrate la gestisce.
`STORE_DESTROYED`	Ci si è iscritti a uno store distrutto o gli si è chiesto di usare l’archivio.

Scritto per l’API di restate 1.0