restate / v1.0.0

Speichern, wann du willst

Bewahre einen Store in IndexedDB oder MMKV auf, lade ihn einmal beim Start, speichere explizit oder automatisch und zeige ungespeicherte Änderungen an.

Auf dieser Seite

Einen gespeicherten Store deklarieren Einmal beim Start warten Speichern, verwerfen und zurücksetzen Ungespeicherte Änderungen und Fortschritt anzeigen Ausprobieren Automatisch speichern Bevor die Seite geschlossen wird Speicherfehler behandeln

Einen gespeicherten Store deklarieren

Ersetze restate durch persistedRestate und gib ihm einen key. Komponenten nutzen weiter denselben Hook und dasselbe set.

Der gespeicherte Wert wird nach dem Erstellen automatisch wiederhergestellt. Bearbeiten ändert den Arbeitsspeicher; geschrieben wird erst, wenn du speicherst oder autoSave einschaltest.

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

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

Einmal beim Start warten

Importiere am Client-Einstiegspunkt die App und ihre Stores und warte vor dem Rendern auf restateManager.ready. Danach können Komponenten gespeicherte Werte direkt lesen.

Nicht verfügbarer Speicher, etwa beim Server-Rendering oder in einem Browser, der ihn blockiert, ist kein Fehler: Diese Stores arbeiten im Arbeitsspeicher. ready wird nur abgelehnt, wenn Datensätze nicht gelesen, migriert oder validiert werden können.

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

Speichern, verwerfen und zurücksetzen

save schreibt den aktuellen Wert, restore kehrt zum gespeicherten Wert zurück und resetAll leert Arbeitsspeicher und Speicher. Jede Methode gibt eine Promise zurück.

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

Ungespeicherte Änderungen und Fortschritt anzeigen

useStatus rendert neu, wenn sich der Persistenzstatus ändert. dirty ist true, solange sich der Arbeitsspeicher vom zuletzt geladenen, gespeicherten oder wiederhergestellten Wert unterscheidet. operation nennt die laufende Speicheroperation.

Übergib einen selector, um nur bei Änderung eines Felds neu zu rendern.

Statusfelder

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

Ein fehlgeschlagener Speichervorgang lässt dirty auf true und setzt error. Die nächste erfolgreiche Speicheroperation löscht 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>}
    </>
  );
}

Ausprobieren

Tipp, erhöhe die Speicherlatenz und speichere. Spiel das Beispiel erneut ab, um den gespeicherten Entwurf wiederhergestellt zu sehen.

ControllerGehört nicht zum Beispielcode. Die Werte erreichen das Beispiel als Props.

Speicherlatenzlatency

<Example
  latency={600}
/>

Beispiel wird vorbereitet…

Live-Beispiele brauchen JavaScript. Der Code unten lässt sich so lesen.

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>
        Entwurf
        <textarea value={text} onChange={(event) => useDraft.set(event.target.value)} />
      </label>
      <div className="actions">
        <button disabled={!dirty} onClick={save}>
          Speichern
        </button>
        <button disabled={!dirty} onClick={revert}>
          Verwerfen
        </button>
      </div>
      <dl className="status">
        <dt>dirty</dt>
        <dd className={dirty ? 'warn' : 'ok'}>
          {dirty ? 'ungespeicherte Änderungen' : 'gespeichert'}
        </dd>
        <dt>operation</dt>
        <dd>{operation ?? 'keine'}</dd>
        <dt>pending</dt>
        <dd>{pending}</dd>
        <dt>lastSavedAt</dt>
        <dd>{lastSavedAt ? new Date(lastSavedAt).toLocaleTimeString() : 'noch nicht'}</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 speichern

Für Einstellungen und Entwürfe, die immer erhalten bleiben sollen, reicht ein einmaliges Opt-in. autoSave: true speichert nach jeder Änderung; { delayMs } wartet, bis die Änderungen pausieren.

Viele schnelle Änderungen werden zu einem Schreibvorgang, und eine Rückkehr zum gespeicherten Wert schreibt nichts. Fehler erscheinen in status().error. Ein komponenteneigener Scope schreibt eine ausstehende Änderung, wenn er unmountet.

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

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

Bevor die Seite geschlossen wird

Lies denselben Status außerhalb von React. Warne vor dem Verlassen bei ungespeicherten Änderungen oder speichere alles, wenn die Seite ausgeblendet wird.

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

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

Speicherfehler behandeln

Speicherfehler lehnen die Promise der Operation ab. Jeder restate-Fehler hat einen code und bei gespeicherten Stores den key des Datensatzes.

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

Geschrieben für die API von restate 1.0