restate / v1.0.0

Αποθηκεύστε όταν αποφασίσετε

Κρατήστε ένα store στο IndexedDB ή στο MMKV, φορτώστε το μία φορά στην εκκίνηση, αποθηκεύστε ρητά ή αυτόματα και δείξτε τις μη αποθηκευμένες αλλαγές.

Σε αυτή τη σελίδα

Δήλωση αποθηκευμένου store Περιμένετε μία φορά στην εκκίνηση Αποθήκευση, αναίρεση και επαναφορά Εμφάνιση μη αποθηκευμένων αλλαγών και προόδου Δοκιμάστε το Αυτόματη αποθήκευση Πριν κλείσει η σελίδα Χειρισμός σφαλμάτων αποθήκευσης

Δήλωση αποθηκευμένου store

Αντικαταστήστε το restate με το persistedRestate και δώστε του ένα key. Τα components συνεχίζουν να χρησιμοποιούν το ίδιο hook και το ίδιο set.

Η αποθηκευμένη τιμή ανακτάται αυτόματα μετά τη δημιουργία. Η επεξεργασία αλλάζει τη μνήμη· τίποτα δεν γράφεται μέχρι να αποθηκεύσετε ή να ενεργοποιήσετε το autoSave.

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

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

Περιμένετε μία φορά στην εκκίνηση

Στο σημείο εισόδου του client, εισαγάγετε την εφαρμογή και τα stores της και περιμένετε το restateManager.ready πριν από την απόδοση. Από εκεί και πέρα τα components μπορούν να διαβάζουν απευθείας τις αποθηκευμένες τιμές.

Η μη διαθέσιμη αποθήκευση, όπως στην απόδοση στον διακομιστή ή σε πρόγραμμα περιήγησης που την μπλοκάρει, δεν είναι σφάλμα: τέτοια stores τρέχουν στη μνήμη. Το ready απορρίπτεται μόνο όταν οι εγγραφές δεν μπορούν να διαβαστούν, να μεταφερθούν ή να επικυρωθούν.

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 γράφει την τρέχουσα τιμή, το restore επιστρέφει στην αποθηκευμένη και το resetAll καθαρίζει μνήμη και αποθήκευση. Το καθένα επιστρέφει 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

Εμφάνιση μη αποθηκευμένων αλλαγών και προόδου

Το useStatus αποδίδεται ξανά όταν αλλάζει η κατάσταση αποθήκευσης. Το dirty είναι true όσο η μνήμη διαφέρει από την τελευταία τιμή που φορτώθηκε, αποθηκεύτηκε ή ανακτήθηκε. Το operation ονομάζει την τρέχουσα λειτουργία αποθήκευσης.

Δώστε έναν selector για να αποδίδεται ξανά μόνο όταν αλλάζει ένα πεδίο.

Πεδία κατάστασης

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

Μια αποτυχημένη αποθήκευση αφήνει το dirty σε true και ορίζει το error. Η επόμενη επιτυχημένη λειτουργία αποθήκευσης καθαρίζει το 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>}
    </>
  );
}

Δοκιμάστε το

Πληκτρολογήστε, αυξήστε την καθυστέρηση αποθήκευσης και αποθηκεύστε. Επαναλάβετε το παράδειγμα για να δείτε το ανακτημένο πρόχειρο.

ΕλεγκτήςΔεν είναι μέρος του κώδικα του παραδείγματος. Οι τιμές φτάνουν στο παράδειγμα ως props.

Καθυστέρηση αποθήκευσηςlatency

<Example
  latency={600}
/>

Προετοιμασία παραδείγματος…

Τα ζωντανά παραδείγματα χρειάζονται JavaScript. Μπορείτε να διαβάσετε τον κώδικα παρακάτω όπως είναι.

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>
        Πρόχειρο
        <textarea value={text} onChange={(event) => useDraft.set(event.target.value)} />
      </label>
      <div className="actions">
        <button disabled={!dirty} onClick={save}>
          Αποθήκευση
        </button>
        <button disabled={!dirty} onClick={revert}>
          Απόρριψη αλλαγών
        </button>
      </div>
      <dl className="status">
        <dt>dirty</dt>
        <dd className={dirty ? 'warn' : 'ok'}>
          {dirty ? 'μη αποθηκευμένες αλλαγές' : 'αποθηκεύτηκε'}
        </dd>
        <dt>operation</dt>
        <dd>{operation ?? 'καμία'}</dd>
        <dt>pending</dt>
        <dd>{pending}</dd>
        <dt>lastSavedAt</dt>
        <dd>{lastSavedAt ? new Date(lastSavedAt).toLocaleTimeString() : 'όχι ακόμη'}</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);
  },
};

Αυτόματη αποθήκευση

Ενεργοποιήστε την μία φορά για ρυθμίσεις και πρόχειρα που πρέπει πάντα να αποθηκεύονται. Το autoSave: true αποθηκεύει μετά από κάθε αλλαγή· το { delayMs } περιμένει να σταματήσουν οι αλλαγές.

Μια σειρά αλλαγών γίνεται μία εγγραφή, και η επιστροφή στην αποθηκευμένη τιμή δεν γράφει τίποτα. Τα σφάλματα εμφανίζονται στο status().error. Το scope ενός component γράφει την εκκρεμή αλλαγή κατά την αποπροσάρτηση.

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

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

Πριν κλείσει η σελίδα

Διαβάστε την ίδια κατάσταση εκτός React. Προειδοποιήστε για μη αποθηκευμένες αλλαγές πριν από την αποχώρηση ή αποθηκεύστε τα πάντα όταν η σελίδα κρυφτεί.

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

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

Χειρισμός σφαλμάτων αποθήκευσης

Τα σφάλματα αποθήκευσης απορρίπτουν το Promise της λειτουργίας. Κάθε σφάλμα του restate έχει code, και στα αποθηκευμένα stores και το 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'}".`);
}

Γραμμένο για το API του restate 1.0