Playground

Change the inputs. Watch restate respond.

Seven experiments run the real package. The controller on the left belongs to this website; the example on the right only receives props, so its code shows exactly what you would write.

Controller — website onlyprops — the bridgeExample — the code you copy

Two screens, one store

Several components need the same value. Declare it once and read it anywhere.

What to watch

Press the step button: every reader shows the new number at the same time.
Change the number of readers: a new reader starts from the current value.

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

Readersreaders
Stepstep

<Example
  readers={3}
  step={1}
/>

Preparing the example…

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

App.jsx

import { restate } from '@kkwaenggwari/restate';
import './styles.css';

const useCount = restate(0);

function Reader({ name }) {
  const count = useCount();

  return (
    <section className="card">
      <span>{name}</span>
      <output>{count}</output>
    </section>
  );
}

export default function Example({ readers = 3, step = 1 }) {
  return (
    <main>
      <div className="grid">
        {Array.from({ length: readers }, (_, index) => (
          <Reader key={index} name={`Screen ${index + 1}`} />
        ))}
      </div>
      <div className="actions">
        <button onClick={() => useCount.set((count) => count + step)}>+{step}</button>
        <button onClick={() => useCount.reset()}>Reset</button>
      </div>
    </main>
  );
}

Get started

Render only what changed

A large store should not re-render every component on every change.

What to watch

Edit note: only the whole-store card renders.
Add item: items and summary render; the coupon card stays still.
Turn shallow off: the summary renders on every change, because its selector returns a new object each time.

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

Compare the summary with shallowshallowSummary

<Example
  shallowSummary={true}
/>

Preparing the example…

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

App.jsx

import { memo, useRef } from 'react';
import { restate, shallow } from '@kkwaenggwari/restate';
import './styles.css';

const useCart = restate({ items: ['Book'], coupon: '', note: '' });

function Card({ title, value }) {
  const renders = useRef(0);
  renders.current += 1;

  return (
    <section className="card">
      <span>{title}</span>
      <output>{value}</output>
      <small>{`${renders.current} renders`}</small>
    </section>
  );
}

const ItemCount = memo(function ItemCount() {
  const count = useCart((cart) => cart.items.length);
  return <Card title="Items" value={count} />;
});

const Coupon = memo(function Coupon() {
  const coupon = useCart((cart) => cart.coupon);
  return <Card title="Coupon" value={coupon || 'none'} />;
});

const Summary = memo(function Summary({ compare }) {
  const summary = useCart((cart) => ({ count: cart.items.length, coupon: cart.coupon }), compare);
  return <Card title="Summary" value={`${summary.count} · ${summary.coupon || '-'}`} />;
});

const Whole = memo(function Whole() {
  const cart = useCart();
  return <Card title="Whole store" value={cart.note.length} />;
});

export default function Example({ shallowSummary = true }) {
  return (
    <main>
      <div className="grid">
        <ItemCount />
        <Coupon />
        <Summary compare={shallowSummary ? shallow : undefined} />
        <Whole />
      </div>
      <div className="actions">
        <button onClick={() => useCart.set((cart) => ({ ...cart, items: [...cart.items, 'Pen'] }))}>
          Add item
        </button>
        <button
          onClick={() => useCart.set((cart) => ({ ...cart, coupon: cart.coupon ? '' : 'SPRING' }))}
        >
          Toggle coupon
        </button>
        <button onClick={() => useCart.set((cart) => ({ ...cart, note: cart.note + '!' }))}>
          Edit note
        </button>
      </div>
    </main>
  );
}

Select only what you need

Many changes, one notification

Updating two stores one by one lets a subscriber see a half-finished state.

What to watch

Clear separately: the subscriber sees 0 items together with the old coupon.
Clear with batch: the subscriber runs once, after both stores changed.

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

Itemsquantity
Couponcoupon

<Example
  quantity={3}
  coupon="SPRING"
/>

Preparing the example…

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

App.jsx

import { useEffect, useState } from 'react';
import { batch, restate } from '@kkwaenggwari/restate';
import './styles.css';

const useItems = restate([]);
const useCoupon = restate('');

export default function Example({ quantity = 3, coupon = 'SPRING' }) {
  const items = useItems();
  const code = useCoupon();
  const [notices, setNotices] = useState([]);

  useEffect(() => {
    useItems.set(Array.from({ length: quantity }, (_, index) => `#${index + 1}`));
    useCoupon.set(coupon);
    setNotices([]);
  }, [quantity, coupon]);

  useEffect(
    () =>
      useItems.subscribe((next) => {
        const notice = `Notified: ${next.length} items · coupon ${useCoupon.get() || '-'}`;
        setNotices((list) => [...list, notice]);
      }),
    [],
  );

  const clear = () => {
    useItems.set([]);
    useCoupon.set('');
  };

  return (
    <main>
      <div className="grid">
        <section className="card">
          <span>Items</span>
          <output>{items.length}</output>
        </section>
        <section className="card">
          <span>Coupon</span>
          <output>{code || '-'}</output>
        </section>
      </div>
      <div className="actions">
        <button onClick={clear}>Clear separately</button>
        <button onClick={() => batch(clear)}>Clear with batch</button>
      </div>
      <h2>What the subscriber saw</h2>
      <ol className="log">
        {notices.length ? (
          notices.map((notice, index) => <li key={index}>{notice}</li>)
        ) : (
          <li>No notifications yet.</li>
        )}
      </ol>
    </main>
  );
}

Select only what you need

Save when you decide

Editing changes memory. Saving is an explicit action, and the status shows what is happening.

What to watch

Type: dirty turns on and nothing is written yet.
Raise the latency and save: operation shows save while the write runs.
Replay: the saved draft is restored from IndexedDB.

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 when you decide

Type fast, write once

Saving on every keystroke floods storage. autoSave waits for a pause.

What to watch

Type a sentence: edits climb quickly while writes grow by one after each pause.
Choose every change: each edit writes, but an edit back to the saved value writes nothing.

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

autoSave delaydelayMs

<Example
  delayMs={800}
/>

Preparing the example…

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

App.jsx

import { useState } from 'react';
import { persistedRestate, useRestateScope } from '@kkwaenggwari/restate';
import { countingStorage, useWrites } from './storage.js';
import './styles.css';

function Note({ delayMs }) {
  const useNote = useRestateScope((scope) =>
    persistedRestate('', {
      scope,
      key: 'note',
      storage: countingStorage,
      autoSave: delayMs ? { delayMs } : true,
    }),
  );
  const note = useNote();
  const dirty = useNote.useStatus((status) => status.dirty);
  const writes = useWrites();
  const [edits, setEdits] = useState(0);

  return (
    <>
      <label>
        Note
        <textarea
          value={note}
          placeholder="Type a sentence quickly…"
          onChange={(event) => {
            useNote.set(event.target.value);
            setEdits((count) => count + 1);
          }}
        />
      </label>
      <div className="grid">
        <section className="card">
          <span>Edits</span>
          <output>{edits}</output>
        </section>
        <section className="card accent">
          <span>Storage writes</span>
          <output>{writes}</output>
        </section>
      </div>
      <p className={dirty ? 'badge warn' : 'badge ok'}>{dirty ? 'waiting for a pause' : 'saved'}</p>
    </>
  );
}

export default function Example({ delayMs = 800 }) {
  // autoSave is part of the declaration: a new delay starts a new scope.
  return (
    <main>
      <Note key={delayMs} delayMs={delayMs} />
    </main>
  );
}

storage.js

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

// An in-memory storage adapter that counts real writes.
const records = new Map();
export const useWrites = restate(0);

export const countingStorage = {
  getItem: (key) => records.get(key) ?? null,
  setItem: (key, value) => {
    records.set(key, value);
    useWrites.set((count) => count + 1);
  },
  removeItem: (key) => {
    records.delete(key);
  },
};

Save when you decide

Failure lab

Make storage slow, failing or unavailable, and watch restate keep your data and report the problem.

What to watch

Raise the latency and save three times: the requests share one write, so pending stays at 1 and all three results arrive together.
Turn on failing writes and save: dirty stays true and error shows the cause.
Make storage unavailable: saving rejects with STORAGE_UNAVAILABLE while editing keeps working.

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

Latencylatency
Fail writesfailWrites
Storage unavailableunavailable

<Example
  latency={700}
  failWrites={false}
  unavailable={false}
/>

Preparing the example…

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

App.jsx

import { useEffect, useState } from 'react';
import { persistedRestate } from '@kkwaenggwari/restate';
import { flakyStorage, settings } from './storage.js';
import './styles.css';

const useNote = persistedRestate('', { key: 'lab-note', storage: flakyStorage });

export default function Example({ latency = 700, failWrites = false, unavailable = false }) {
  useEffect(() => {
    Object.assign(settings, { latency, failWrites, unavailable });
  }, [latency, failWrites, unavailable]);

  const note = useNote();
  const { dirty, operation, pending, error } = useNote.useStatus();
  const [results, setResults] = useState([]);

  const save = () =>
    useNote.save().then(
      (value) => setResults((list) => [`Saved ${JSON.stringify(value)}`, ...list]),
      (reason) => setResults((list) => [`Failed: ${reason.code ?? reason.message}`, ...list]),
    );

  return (
    <main>
      <label>
        Note
        <input value={note} onChange={(event) => useNote.set(event.target.value)} />
      </label>
      <div className="actions">
        <button onClick={save}>Save</button>
        <button
          onClick={() => {
            save();
            save();
            save();
          }}
        >
          Save three times
        </button>
      </div>
      <dl className="status">
        <dt>dirty</dt>
        <dd className={dirty ? 'warn' : 'ok'}>{String(dirty)}</dd>
        <dt>operation</dt>
        <dd>{operation ?? '-'}</dd>
        <dt>pending</dt>
        <dd>{pending}</dd>
        <dt>error</dt>
        <dd className={error ? 'bad' : ''}>{error ? (error.code ?? error.message) : '-'}</dd>
      </dl>
      <h2>Results</h2>
      <ol className="log">
        {results.length ? (
          results.map((result, index) => <li key={results.length - index}>{result}</li>)
        ) : (
          <li>-</li>
        )}
      </ol>
    </main>
  );
}

storage.js

// A storage adapter whose speed and failures you can change.
const records = new Map();
export const settings = { latency: 0, failWrites: false, unavailable: false };
const wait = () => new Promise((resolve) => setTimeout(resolve, settings.latency));

export const flakyStorage = {
  isAvailable: () => !settings.unavailable,
  async getItem(key) {
    await wait();
    return records.get(key) ?? null;
  },
  async setItem(key, value) {
    await wait();
    if (settings.failWrites) throw new Error('The disk is full');
    records.set(key, value);
  },
  async removeItem(key) {
    await wait();
    records.delete(key);
  },
};

Reliability by design

State per document

Each open document needs its own state, released when the document closes.

What to watch

Type in document A, then in B: each keeps its own text.
Close document A and open it again: it starts empty, because its scope was destroyed.

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

Documentsdocuments
Document A openfirstOpen

<Example
  documents={2}
  firstOpen={true}
/>

Preparing the example…

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

App.jsx

import { restate, useRestateScope } from '@kkwaenggwari/restate';
import './styles.css';

function Document({ name }) {
  const useText = useRestateScope((scope) => restate('', { scope }));
  const text = useText();

  return (
    <section className="card">
      <span>{name}</span>
      <input
        value={text}
        placeholder="Typed only here"
        onChange={(event) => useText.set(event.target.value)}
      />
      <small>{`${text.length} characters`}</small>
    </section>
  );
}

export default function Example({ documents = 2, firstOpen = true }) {
  const names = ['A', 'B', 'C'].slice(0, documents);

  return (
    <main>
      <div className="grid">
        {names.map((name, index) =>
          index === 0 && !firstOpen ? null : <Document key={name} name={`Document ${name}`} />,
        )}
      </div>
    </main>
  );
}

State owned by a component