restate / v1.0.0

Salvați când decideți

Păstrați un store în IndexedDB sau MMKV, încărcați-l o dată la pornire, salvați explicit sau automat și arătați modificările nesalvate.

Pe această pagină

Declararea unui store salvat Așteptați o dată la pornire Salvare, anulare și resetare Afișarea modificărilor nesalvate și a progresului Încercați Salvare automată Înainte de închiderea paginii Tratarea erorilor de stocare

Declararea unui store salvat

Înlocuiți restate cu persistedRestate și dați-i un key. Componentele folosesc în continuare același hook și același set.

Valoarea salvată se restaurează automat după creare. Editarea schimbă memoria; nu se scrie nimic până nu salvați sau activați autoSave.

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

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

Așteptați o dată la pornire

În punctul de intrare de pe client, importați aplicația și store-urile ei, apoi așteptați restateManager.ready înainte de randare. De acolo, componentele pot citi direct valorile salvate.

Stocarea indisponibilă, de exemplu la randarea pe server sau într-un browser care o blochează, nu este o eroare: astfel de store-uri rulează în memorie. ready e respins doar când înregistrările nu pot fi citite, migrate sau validate.

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

Salvare, anulare și resetare

save scrie valoarea curentă, restore revine la valoarea salvată, iar resetAll golește memoria și stocarea. Fiecare returnează un 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

Afișarea modificărilor nesalvate și a progresului

useStatus se re-randează când se schimbă starea salvării. dirty este true cât timp memoria diferă de ultima valoare încărcată, salvată sau restaurată. operation numește operațiunea de stocare în curs.

Dați un selector ca să se re-randeze doar când se schimbă un singur câmp.

Câmpuri de status

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

O salvare eșuată lasă dirty pe true și setează error. Următoarea operațiune de stocare reușită golește 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>}
    </>
  );
}

Încercați

Tastați, măriți întârzierea stocării și salvați. Redați exemplul ca să vedeți ciorna restaurată.

ControlerNu face parte din codul exemplului. Valorile ajung în exemplu ca props.

Întârzierea stocăriilatency

<Example
  latency={600}
/>

Se pregătește exemplul…

Exemplele live au nevoie de JavaScript. Puteți citi codul de mai jos așa cum este.

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>
        Ciornă
        <textarea value={text} onChange={(event) => useDraft.set(event.target.value)} />
      </label>
      <div className="actions">
        <button disabled={!dirty} onClick={save}>
          Salvează
        </button>
        <button disabled={!dirty} onClick={revert}>
          Renunță la modificări
        </button>
      </div>
      <dl className="status">
        <dt>dirty</dt>
        <dd className={dirty ? 'warn' : 'ok'}>{dirty ? 'modificări nesalvate' : 'salvat'}</dd>
        <dt>operation</dt>
        <dd>{operation ?? 'niciuna'}</dd>
        <dt>pending</dt>
        <dd>{pending}</dd>
        <dt>lastSavedAt</dt>
        <dd>{lastSavedAt ? new Date(lastSavedAt).toLocaleTimeString() : 'încă nu'}</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);
  },
};

Salvare automată

Activați-o o dată pentru setări și ciorne care trebuie mereu salvate. autoSave: true salvează după fiecare schimbare; { delayMs } așteaptă să se oprească modificările.

O serie de modificări devine o singură scriere, iar revenirea la valoarea salvată nu scrie nimic. Erorile apar în status().error. Scope-ul unei componente scrie modificarea în așteptare la demontare.

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

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

Înainte de închiderea paginii

Citiți același status în afara React. Avertizați despre modificările nesalvate înainte de plecare sau salvați tot când pagina e ascunsă.

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

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

Tratarea erorilor de stocare

Erorile de stocare resping Promise-ul operațiunii. Fiecare eroare restate are un code, iar pentru store-urile salvate și key-ul înregistrării.

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

Scris pentru API-ul restate 1.0