restate / v1.0.0

Lưu khi bạn quyết định

Giữ store trong IndexedDB hoặc MMKV, tải một lần khi khởi động, lưu tường minh hoặc tự động và hiển thị thay đổi chưa lưu.

Trên trang này

Khai báo store được lưu Chờ một lần khi khởi động Lưu, hoàn tác và đặt lại Hiển thị thay đổi chưa lưu và tiến độ Thử ngay Tự động lưu Trước khi đóng trang Xử lý lỗi lưu trữ

Khai báo store được lưu

Thay restate bằng persistedRestate và đặt cho nó một key. Component vẫn dùng cùng hook và cùng set.

Giá trị đã lưu được tự động khôi phục sau khi tạo. Chỉnh sửa thay đổi bộ nhớ; không có gì được ghi cho đến khi bạn lưu hoặc bật autoSave.

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

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

Chờ một lần khi khởi động

Ở điểm vào phía client, import ứng dụng và các store của nó, rồi chờ restateManager.ready trước khi render. Từ đó component có thể đọc trực tiếp các giá trị đã lưu.

Bộ nhớ lưu trữ không khả dụng, như khi render phía máy chủ hoặc trong trình duyệt chặn nó, không phải lỗi: những store đó chạy trong bộ nhớ. ready chỉ bị từ chối khi bản ghi không thể đọc, di chuyển hoặc kiểm tra hợp lệ.

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

Lưu, hoàn tác và đặt lại

save ghi giá trị hiện tại, restore quay về giá trị đã lưu, còn resetAll xóa cả bộ nhớ lẫn bộ nhớ lưu trữ. Mỗi hàm trả về một 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

Hiển thị thay đổi chưa lưu và tiến độ

useStatus render lại khi trạng thái lưu thay đổi. dirty là true khi bộ nhớ khác với giá trị được tải, lưu hoặc khôi phục gần nhất. operation cho biết thao tác lưu trữ hiện tại.

Truyền selector để chỉ render lại khi một trường thay đổi.

Các trường trạng thái

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

Lần lưu thất bại giữ dirty là true và đặt error. Thao tác lưu trữ thành công tiếp theo sẽ xóa 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>}
    </>
  );
}

Thử ngay

Gõ, tăng độ trễ lưu trữ rồi lưu. Phát lại ví dụ để thấy bản nháp được khôi phục.

Bộ điều khiểnKhông thuộc mã ví dụ. Các giá trị đi vào ví dụ dưới dạng props.

Độ trễ lưu trữlatency

<Example
  latency={600}
/>

Đang chuẩn bị ví dụ…

Ví dụ trực tiếp cần JavaScript. Bạn vẫn có thể đọc đoạn mã bên dưới như hiện có.

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>
        Bản nháp
        <textarea value={text} onChange={(event) => useDraft.set(event.target.value)} />
      </label>
      <div className="actions">
        <button disabled={!dirty} onClick={save}>
          Lưu
        </button>
        <button disabled={!dirty} onClick={revert}>
          Bỏ thay đổi
        </button>
      </div>
      <dl className="status">
        <dt>dirty</dt>
        <dd className={dirty ? 'warn' : 'ok'}>{dirty ? 'có thay đổi chưa lưu' : 'đã lưu'}</dd>
        <dt>operation</dt>
        <dd>{operation ?? 'không có'}</dd>
        <dt>pending</dt>
        <dd>{pending}</dd>
        <dt>lastSavedAt</dt>
        <dd>{lastSavedAt ? new Date(lastSavedAt).toLocaleTimeString() : 'chưa'}</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);
  },
};

Tự động lưu

Bật một lần cho cài đặt và bản nháp luôn cần được lưu. autoSave: true lưu sau mỗi thay đổi; { delayMs } chờ đến khi thay đổi dừng lại.

Một loạt thay đổi trở thành một lần ghi, và quay về giá trị đã lưu thì không ghi gì. Lỗi xuất hiện trong status().error. Scope của component ghi thay đổi đang chờ khi unmount.

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

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

Trước khi đóng trang

Đọc cùng trạng thái đó bên ngoài React. Cảnh báo thay đổi chưa lưu trước khi rời trang, hoặc lưu tất cả khi trang bị ẩn.

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

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

Xử lý lỗi lưu trữ

Lỗi lưu trữ làm Promise của thao tác bị từ chối. Mỗi lỗi restate có code, và với store được lưu còn có key của bản ghi.

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

Viết cho API restate 1.0