restate / v1.0.0

Spara när du bestämmer

Spara en store i IndexedDB eller MMKV, läs in den en gång vid start, spara explicit eller automatiskt och visa osparade ändringar.

På den här sidan

Deklarera en sparad store Vänta en gång vid start Spara, ångra och återställ Visa osparade ändringar och förlopp Prova Spara automatiskt Innan sidan stängs Hantera lagringsfel

Deklarera en sparad store

Byt restate mot persistedRestate och ge den en key. Komponenterna använder fortfarande samma hook och samma set.

Det sparade värdet återställs automatiskt efter att storen skapats. Att redigera ändrar minnet; ingenting skrivs förrän du sparar eller slår på autoSave.

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

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

Vänta en gång vid start

Importera appen och dess stores i klientens startpunkt och vänta sedan på restateManager.ready innan du renderar. Därefter kan komponenterna läsa sparade värden direkt.

Otillgänglig lagring, som vid serverrendering eller i en webbläsare som blockerar den, är inget fel: de storesen fungerar i minnet. ready avvisas bara när poster inte kan läsas, migreras eller valideras.

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

Spara, ångra och återställ

save skriver det aktuella värdet, restore går tillbaka till det sparade värdet och resetAll rensar både minne och lagring. Var och en returnerar ett 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

Visa osparade ändringar och förlopp

useStatus renderas om när sparstatusen ändras. dirty är true så länge minnet skiljer sig från det senast inlästa, sparade eller återställda värdet. operation namnger den pågående lagringsåtgärden.

Skicka en selector för att bara rendera om när ett fält ändras.

Statusfält

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

En misslyckad sparning lämnar dirty som true och sätter error. Nästa lyckade lagringsåtgärd rensar 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>}
    </>
  );
}

Prova

Skriv, öka lagringsfördröjningen och spara. Spela upp exemplet igen för att se det sparade utkastet återställt.

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

Lagringsfördröjninglatency

<Example
  latency={600}
/>

Förbereder exemplet…

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

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>
        Utkast
        <textarea value={text} onChange={(event) => useDraft.set(event.target.value)} />
      </label>
      <div className="actions">
        <button disabled={!dirty} onClick={save}>
          Spara
        </button>
        <button disabled={!dirty} onClick={revert}>
          Kasta ändringar
        </button>
      </div>
      <dl className="status">
        <dt>dirty</dt>
        <dd className={dirty ? 'warn' : 'ok'}>{dirty ? 'osparade ändringar' : 'sparat'}</dd>
        <dt>operation</dt>
        <dd>{operation ?? 'ingen'}</dd>
        <dt>pending</dt>
        <dd>{pending}</dd>
        <dt>lastSavedAt</dt>
        <dd>{lastSavedAt ? new Date(lastSavedAt).toLocaleTimeString() : 'inte än'}</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);
  },
};

Spara automatiskt

Slå på det en gång för inställningar och utkast som alltid ska sparas. autoSave: true sparar efter varje ändring; { delayMs } väntar tills ändringarna upphör.

En serie ändringar blir en skrivning, och att gå tillbaka till det sparade värdet skriver ingenting. Fel syns i status().error. Ett komponentscope skriver den väntande ändringen vid unmount.

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

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

Innan sidan stängs

Läs samma state utanför React. Varna innan användaren lämnar om det finns osparade ändringar, eller spara allt när sidan döljs.

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

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

Hantera lagringsfel

Lagringsfel avvisar åtgärdens Promise. Varje restate-fel har en code och, för sparade stores, postens key.

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

Skrivet för API:t i restate 1.0