restate / v1.0.0

Sla op wanneer jij besluit

Bewaar een store in IndexedDB of MMKV, laad hem één keer bij het opstarten, sla expliciet of automatisch op en toon niet-opgeslagen bewerkingen.

Op deze pagina

Declareer een opgeslagen store Wacht één keer bij het opstarten Opslaan, ongedaan maken en resetten Toon niet-opgeslagen bewerkingen en voortgang Probeer het Automatisch opslaan Voordat de pagina sluit Opslagfouten afhandelen

Declareer een opgeslagen store

Vervang restate door persistedRestate en geef hem een key. Componenten blijven dezelfde hook en dezelfde set gebruiken.

De opgeslagen waarde wordt na het aanmaken automatisch teruggezet. Bewerken verandert het geheugen; er wordt niets geschreven totdat je opslaat of autoSave inschakelt.

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

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

Wacht één keer bij het opstarten

Importeer in het client-toegangspunt je app en haar stores, en wacht dan op restateManager.ready voordat je rendert. Daarna kunnen componenten opgeslagen waarden direct lezen.

Onbeschikbare opslag, zoals bij server-rendering of in een browser die het blokkeert, is geen fout: die stores werken in het geheugen. ready wordt alleen geweigerd als records niet kunnen worden gelezen, gemigreerd of gevalideerd.

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

Opslaan, ongedaan maken en resetten

save schrijft de huidige waarde, restore gaat terug naar de opgeslagen waarde en resetAll wist zowel het geheugen als de opslag. Elk geeft een Promise terug.

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

Toon niet-opgeslagen bewerkingen en voortgang

useStatus rendert opnieuw als de opslagstatus verandert. dirty is true zolang het geheugen afwijkt van de laatst geladen, opgeslagen of teruggezette waarde. operation noemt de lopende opslagbewerking.

Geef een selector door om alleen opnieuw te renderen als één veld verandert.

Statusvelden

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

Een mislukte save laat dirty op true staan en vult error. De volgende geslaagde opslagbewerking wist 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>}
    </>
  );
}

Probeer het

Typ, verhoog de opslagvertraging en sla op. Speel het voorbeeld opnieuw af om het opgeslagen concept teruggezet te zien.

ControllerGeen onderdeel van de voorbeeldcode. Waarden komen als props in het voorbeeld.

Opslagvertraginglatency

<Example
  latency={600}
/>

Voorbeeld voorbereiden…

Live voorbeelden hebben JavaScript nodig. De code hieronder is gewoon te lezen.

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>
        Concept
        <textarea value={text} onChange={(event) => useDraft.set(event.target.value)} />
      </label>
      <div className="actions">
        <button disabled={!dirty} onClick={save}>
          Opslaan
        </button>
        <button disabled={!dirty} onClick={revert}>
          Bewerkingen verwerpen
        </button>
      </div>
      <dl className="status">
        <dt>dirty</dt>
        <dd className={dirty ? 'warn' : 'ok'}>
          {dirty ? 'niet-opgeslagen bewerkingen' : 'opgeslagen'}
        </dd>
        <dt>operation</dt>
        <dd>{operation ?? 'geen'}</dd>
        <dt>pending</dt>
        <dd>{pending}</dd>
        <dt>lastSavedAt</dt>
        <dd>{lastSavedAt ? new Date(lastSavedAt).toLocaleTimeString() : 'nog niet'}</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);
  },
};

Automatisch opslaan

Zet het één keer aan voor instellingen en concepten die altijd bewaard moeten blijven. autoSave: true slaat na elke wijziging op; { delayMs } wacht tot de bewerkingen stoppen.

Een reeks bewerkingen wordt één schrijfactie, en terug naar de opgeslagen waarde schrijft niets. Fouten verschijnen in status().error. Een componentscope schrijft de openstaande bewerking weg bij de unmount.

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

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

Voordat de pagina sluit

Lees dezelfde state buiten React. Waarschuw voor het verlaten als er niet-opgeslagen bewerkingen zijn, of sla alles op zodra de pagina verborgen wordt.

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

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

Opslagfouten afhandelen

Opslagfouten weigeren de Promise van de bewerking. Elke restate-fout heeft een code en, bij opgeslagen stores, de key van het 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'}".`);
}

Geschreven voor de API van restate 1.0