restate / v1.0.0

Lagre når du bestemmer

Ta vare på en store i IndexedDB eller MMKV, last den inn én gang ved oppstart, lagre eksplisitt eller automatisk, og vis ulagrede endringer.

På denne siden

Deklarer en lagret store Vent én gang ved oppstart Lagre, angre og tilbakestill Vis ulagrede endringer og fremdrift Prøv det Lagre automatisk Før siden lukkes Håndter lagringsfeil

Deklarer en lagret store

Bytt restate med persistedRestate og gi den en key. Komponentene bruker fortsatt samme hook og samme set.

Den lagrede verdien gjenopprettes automatisk etter at storen er opprettet. Redigering endrer minnet; ingenting skrives før du lagrer eller slår på autoSave.

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

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

Vent én gang ved oppstart

Importer appen og storene dens i klientens inngangspunkt, og vent deretter på restateManager.ready før du renderer. Derfra kan komponentene lese lagrede verdier direkte.

Utilgjengelig lagring, som ved serverrendering eller i en nettleser som blokkerer den, er ikke en feil: de storene kjører i minnet. ready avvises bare når poster ikke kan leses, migreres eller valideres.

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

Lagre, angre og tilbakestill

save skriver gjeldende verdi, restore går tilbake til den lagrede verdien, og resetAll tømmer både minnet og lagringen. Hver returnerer et 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

Vis ulagrede endringer og fremdrift

useStatus renderes på nytt når lagringsstatusen endres. dirty er true så lenge minnet avviker fra den sist innlastede, lagrede eller gjenopprettede verdien. operation angir den pågående lagringsoperasjonen.

Send en selector for bare å rendere på nytt når ett felt endres.

Statusfelt

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 mislykket lagring lar dirty forbli true og setter error. Neste vellykkede lagringsoperasjon tømmer 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>}
    </>
  );
}

Prøv det

Skriv, øk lagringsforsinkelsen og lagre. Spill av eksempelet igjen for å se det lagrede utkastet gjenopprettet.

KontrollerIkke en del av eksempelkoden. Verdiene når eksempelet som props.

Lagringsforsinkelselatency

<Example
  latency={600}
/>

Forbereder eksempelet …

Live-eksempler krever JavaScript. Koden nedenfor kan leses som den er.

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}>
          Lagre
        </button>
        <button disabled={!dirty} onClick={revert}>
          Forkast endringer
        </button>
      </div>
      <dl className="status">
        <dt>dirty</dt>
        <dd className={dirty ? 'warn' : 'ok'}>{dirty ? 'ulagrede endringer' : 'lagret'}</dd>
        <dt>operation</dt>
        <dd>{operation ?? 'ingen'}</dd>
        <dt>pending</dt>
        <dd>{pending}</dd>
        <dt>lastSavedAt</dt>
        <dd>{lastSavedAt ? new Date(lastSavedAt).toLocaleTimeString() : 'ikke ennå'}</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);
  },
};

Lagre automatisk

Slå det på én gang for innstillinger og utkast som alltid skal lagres. autoSave: true lagrer etter hver endring; { delayMs } venter til endringene stopper.

En rekke endringer blir til én skriving, og å gå tilbake til den lagrede verdien skriver ingenting. Feil vises i status().error. Et komponent-scope skriver den ventende endringen ved unmount.

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

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

Før siden lukkes

Les den samme state-en utenfor React. Advar før brukeren forlater siden hvis det finnes ulagrede endringer, eller lagre alt når siden skjules.

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

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

Håndter lagringsfeil

Lagringsfeil avviser operasjonens Promise. Hver restate-feil har en code og, for lagrede 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'}".`);
}

Skrevet for API-et i restate 1.0