restate / v1.0.0

Save when you decide

Keep a store in IndexedDB or MMKV, load it once at startup, save explicitly or automatically, and show unsaved changes.

On this page

Declare a saved store Wait once at startup Save, revert and reset Show unsaved changes and progress Try it Save automatically Before the page closes Handle storage errors

Declare a saved store

Replace restate with persistedRestate and give it a key. Components keep using the same hook and set.

The saved value is restored automatically after creation. Editing changes memory; nothing is written until you save or turn on autoSave.

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

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

Wait once at startup

At the client entry, import the app and its stores, then wait for restateManager.ready before rendering. Components can then read saved values directly.

Storage that is unavailable, such as during server rendering or in a blocked browser, is not a failure: those stores work in memory. ready rejects only when records cannot be read, migrated or validated.

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

Save, revert and reset

save writes the current value, restore returns to the saved value, and resetAll clears both memory and storage. Each returns a 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

Show unsaved changes and progress

useStatus re-renders when the persistence status changes. dirty is true while memory differs from the value last loaded, saved or restored. operation names the running storage operation.

Pass a selector to re-render only when one field changes.

Status fields

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

A failed save keeps dirty true and sets error. The next successful storage operation clears 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>}
    </>
  );
}

Try it

Type, raise the storage latency and save. Replay the example to see the saved draft restored.

ControllerNot part of the example code. Values reach the example as props.

Storage latencylatency

<Example
  latency={600}
/>

Preparing the example…

Live examples need JavaScript. The code below reads as is.

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>
        Draft
        <textarea value={text} onChange={(event) => useDraft.set(event.target.value)} />
      </label>
      <div className="actions">
        <button disabled={!dirty} onClick={save}>
          Save
        </button>
        <button disabled={!dirty} onClick={revert}>
          Revert
        </button>
      </div>
      <dl className="status">
        <dt>dirty</dt>
        <dd className={dirty ? 'warn' : 'ok'}>{dirty ? 'unsaved changes' : 'saved'}</dd>
        <dt>operation</dt>
        <dd>{operation ?? 'none'}</dd>
        <dt>pending</dt>
        <dd>{pending}</dd>
        <dt>lastSavedAt</dt>
        <dd>{lastSavedAt ? new Date(lastSavedAt).toLocaleTimeString() : 'not yet'}</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);
  },
};

Save automatically

For settings and drafts that should always persist, opt in once. autoSave: true saves after each change; { delayMs } waits until changes pause.

A burst of changes becomes one write, and a change back to the saved value writes nothing. Failures appear in status().error. A component-owned scope writes a pending change when it unmounts.

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

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

Before the page closes

Read the same status outside React. Warn before leaving with unsaved changes, or save everything when the page is hidden.

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

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

Handle storage errors

Storage errors reject the Promise of the operation. Every restate error has a code and, for saved stores, the key of the 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'}".`);
}

Written for the restate 1.0 API