restate / v1.0.0

Salva quando decidi tu

Conserva uno store in IndexedDB o MMKV, caricalo una volta all’avvio, salva in modo esplicito o automatico e mostra le modifiche non salvate.

In questa pagina

Dichiara uno store salvato Attendi una volta all’avvio Salva, annulla e reimposta Mostra le modifiche non salvate e l’avanzamento Provalo Salva in automatico Prima di chiudere la pagina Gestisci gli errori di archiviazione

Dichiara uno store salvato

Sostituisci restate con persistedRestate e dagli una key. I componenti continuano a usare lo stesso hook e lo stesso set.

Il valore salvato viene ripristinato in automatico dopo la creazione. Modificare cambia la memoria; non viene scritto nulla finché non salvi o attivi autoSave.

import { persistedRestate } from '@kkwaenggwari/restate';

export const useDraft = persistedRestate('', {
  key: 'article-draft',
  validate: (value) => typeof value === 'string',
});

Attendi una volta all’avvio

Nell’entry point del client importa l’app e i suoi store, poi attendi restateManager.ready prima del render. Da lì i componenti possono leggere direttamente i valori salvati.

Un archivio non disponibile, come durante il rendering sul server o in un browser che lo blocca, non è un errore: quegli store funzionano in memoria. ready viene rifiutato solo quando i record non possono essere letti, migrati o validati.

import { createRoot } from 'react-dom/client';
import { restateManager } from '@kkwaenggwari/restate';
import App from './App';

async function start() {
  const root = createRoot(document.getElementById('root'));
  try {
    await restateManager.ready;
    root.render(<App />);
  } catch (error) {
    root.render(<p>Could not load saved data.</p>);
    console.error(error);
  }
}
start();

Salva, annulla e reimposta

save scrive il valore attuale, restore torna al valore salvato e resetAll svuota sia la memoria sia l’archivio. Ognuno restituisce una Promise.

await useDraft.save(); // write the current value
await useDraft.restore(); // return to the saved value
await useDraft.resetAndClearStorage(); // initial value in memory, record removed

Mostra le modifiche non salvate e l’avanzamento

useStatus si ri-renderizza quando cambia lo stato di persistenza. dirty è true finché la memoria differisce dall’ultimo valore caricato, salvato o ripristinato. operation indica l’operazione di archiviazione in corso.

Passa un selector per ri-renderizzare solo quando cambia un campo.

Campi di stato

dirty      true | false
operation  "save" | "restore" | … | null
pending    number of unsettled operations
error      last storage error or null
available  false when storage cannot be used

Un salvataggio fallito lascia dirty a true e imposta error. La successiva operazione di archiviazione riuscita azzera error.

function SaveButton() {
  const { dirty, operation, error } = useDraft.useStatus();
  const saving = operation === 'save';

  return (
    <>
      <button disabled={!dirty || saving} onClick={() => useDraft.save().catch(() => {})}>
        {saving ? 'Saving…' : 'Save'}
      </button>
      {error != null && <p>Could not save your draft.</p>}
    </>
  );
}

Provalo

Scrivi, aumenta la latenza dell’archivio e salva. Riproduci di nuovo l’esempio per vedere ripristinata la bozza salvata.

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

Latenza dell’archiviolatency

<Example
  latency={600}
/>

Preparazione dell’esempio…

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

App.jsx

import { useEffect } from 'react';
import { persistedRestate } from '@kkwaenggwari/restate';
import { settings, slowStorage } from './storage.js';
import './styles.css';

const useDraft = persistedRestate('', { key: 'playground-draft', storage: slowStorage });

export default function Example({ latency = 600 }) {
  useEffect(() => {
    settings.latency = latency;
  }, [latency]);

  const text = useDraft();
  const { dirty, operation, pending, lastSavedAt } = useDraft.useStatus();
  // A failed save keeps dirty and records status.error.
  const save = () => useDraft.save().catch(() => {});
  const revert = () => useDraft.restore().catch(() => {});

  return (
    <main>
      <label>
        Bozza
        <textarea value={text} onChange={(event) => useDraft.set(event.target.value)} />
      </label>
      <div className="actions">
        <button disabled={!dirty} onClick={save}>
          Salva
        </button>
        <button disabled={!dirty} onClick={revert}>
          Annulla le modifiche
        </button>
      </div>
      <dl className="status">
        <dt>dirty</dt>
        <dd className={dirty ? 'warn' : 'ok'}>{dirty ? 'modifiche non salvate' : 'salvato'}</dd>
        <dt>operation</dt>
        <dd>{operation ?? 'nessuna'}</dd>
        <dt>pending</dt>
        <dd>{pending}</dd>
        <dt>lastSavedAt</dt>
        <dd>{lastSavedAt ? new Date(lastSavedAt).toLocaleTimeString() : 'non ancora'}</dd>
      </dl>
    </main>
  );
}

storage.js

import { createIndexedDBStorage } from '@kkwaenggwari/restate';

// IndexedDB with an adjustable delay, to watch operations in progress.
const indexedDB = createIndexedDBStorage();
export const settings = { latency: 0 };
const wait = () => new Promise((resolve) => setTimeout(resolve, settings.latency));

export const slowStorage = {
  async getItem(key) {
    await wait();
    return indexedDB.getItem(key);
  },
  async setItem(key, value) {
    await wait();
    return indexedDB.setItem(key, value);
  },
  async removeItem(key) {
    await wait();
    return indexedDB.removeItem(key);
  },
};

Salva in automatico

Per impostazioni e bozze che devono sempre persistere, attivalo una volta. autoSave: true salva dopo ogni modifica; { delayMs } aspetta che le modifiche si fermino.

Una raffica di modifiche diventa una sola scrittura, e tornare al valore salvato non scrive nulla. Gli errori compaiono in status().error. Uno scope di un componente scrive la modifica in sospeso quando viene smontato.

export const useTheme = persistedRestate('light', { key: 'theme', autoSave: true });

export const useDraft = persistedRestate('', {
  key: 'article-draft',
  autoSave: { delayMs: 500 },
});

Prima di chiudere la pagina

Leggi lo stesso stato fuori da React. Avvisa prima di uscire se ci sono modifiche non salvate, oppure salva tutto quando la pagina viene nascosta.

window.addEventListener('beforeunload', (event) => {
  if (useDraft.status().dirty) event.preventDefault();
});

window.addEventListener('pagehide', () => {
  restateManager.saveAll();
});

Gestisci gli errori di archiviazione

Gli errori di archiviazione rifiutano la Promise dell’operazione. Ogni errore di restate ha un code e, per gli store salvati, la key del record.

try {
  await useDraft.save();
} catch (error) {
  if (error.code === 'STORAGE_UNAVAILABLE') showNotice('Saving is off in this browser.');
  else if (error.code === 'STORAGE_VALUE_TOO_LARGE') showNotice('This draft is too large.');
  else showNotice(`Could not save "${error.key ?? 'draft'}".`);
}

Scritto per l’API di restate 1.0