restate / v1.0.0

Gem, når du beslutter det

Gem en store i IndexedDB eller MMKV, indlæs den én gang ved opstart, gem eksplicit eller automatisk, og vis ikke-gemte ændringer.

På denne side

Erklær en gemt store Vent én gang ved opstart Gem, fortryd og nulstil Vis ikke-gemte ændringer og fremskridt Prøv det Gem automatisk Før siden lukkes Håndtér lagerfejl

Erklær en gemt store

Skift restate ud med persistedRestate, og giv den en key. Komponenterne bruger stadig samme hook og samme set.

Den gemte værdi gendannes automatisk efter oprettelsen. At redigere ændrer hukommelsen; intet skrives, før du gemmer eller slår autoSave til.

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

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

Vent én gang ved opstart

Importér appen og dens stores i klientens indgangspunkt, og vent derefter på restateManager.ready, før du renderer. Derefter kan komponenterne læse gemte værdier direkte.

Utilgængeligt lager, som ved serverrendering eller i en browser, der blokerer det, er ikke en fejl: de stores kører i hukommelsen. ready afvises kun, når poster ikke kan læses, 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();

Gem, fortryd og nulstil

save skriver den aktuelle værdi, restore går tilbage til den gemte værdi, og resetAll rydder både hukommelse og lager. 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 ikke-gemte ændringer og fremskridt

useStatus renderes igen, når gemmestatus ændrer sig. dirty er true, så længe hukommelsen afviger fra den senest indlæste, gemte eller gendannede værdi. operation angiver den igangværende lagerhandling.

Giv en selector for kun at rendere igen, når ét felt ændrer sig.

Statusfelter

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

Et mislykket gem lader dirty forblive true og sætter error. Den næste vellykkede lagerhandling rydder 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, hæv lagerforsinkelsen, og gem. Afspil eksemplet igen for at se den gemte kladde gendannet.

ControllerIkke en del af eksempelkoden. Værdierne når eksemplet som props.

Lagerforsinkelselatency

<Example
  latency={600}
/>

Forbereder eksemplet…

Liveeksempler kræver JavaScript. Koden nedenfor kan læses, 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>
        Kladde
        <textarea value={text} onChange={(event) => useDraft.set(event.target.value)} />
      </label>
      <div className="actions">
        <button disabled={!dirty} onClick={save}>
          Gem
        </button>
        <button disabled={!dirty} onClick={revert}>
          Kassér ændringer
        </button>
      </div>
      <dl className="status">
        <dt>dirty</dt>
        <dd className={dirty ? 'warn' : 'ok'}>{dirty ? 'ikke-gemte ændringer' : 'gemt'}</dd>
        <dt>operation</dt>
        <dd>{operation ?? 'ingen'}</dd>
        <dt>pending</dt>
        <dd>{pending}</dd>
        <dt>lastSavedAt</dt>
        <dd>{lastSavedAt ? new Date(lastSavedAt).toLocaleTimeString() : 'ikke endnu'}</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);
  },
};

Gem automatisk

Slå det til én gang for indstillinger og kladder, der altid skal gemmes. autoSave: true gemmer efter hver ændring; { delayMs } venter, til ændringerne stopper.

En række ændringer bliver til én skrivning, og at gå tilbage til den gemte værdi skriver ingenting. Fejl vises i status().error. Et komponent-scope skriver den ventende ændring 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

Læs den samme state uden for React. Advar, før brugeren forlader siden, hvis der er ikke-gemte ændringer, eller gem alt, når siden skjules.

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

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

Håndtér lagerfejl

Lagerfejl afviser handlingens Promise. Hver restate-fejl har en code og, for gemte 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 til API'et i restate 1.0