restate / v1.0.0

Αξιόπιστο από τον σχεδιασμό

Τι εγγυάται το restate όταν η αποθήκευση είναι αργή, αποτυγχάνει ή λείπει, και πώς διαβάζετε τα σφάλματα που αναφέρει.

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

Εγγυήσεις Αποθηκεύσεις με σειρά Δοκιμάστε το Όταν αποτυγχάνει η φόρτωση Αποθήκευση και κλείσιμο Η αποθήκευση δεν είναι διαθέσιμη Επικύρωση και μεταφορά αποθηκευμένων δεδομένων Δική σας αποθήκευση Όρια και χρονικά όρια Κωδικοί σφάλματος

Εγγυήσεις

Αυτή η συμπεριφορά είναι μέρος του συμβολαίου 1.0 και καλύπτεται από τα τεστ του πακέτου.

Περίσταση	Τι κάνει το restate
`Πολλές αποθηκεύσεις στη σειρά`	Τις εκτελεί με σειρά ανά store· μια αποθήκευση στην ουρά γράφει την πιο πρόσφατη τιμή.
`Μια εγγραφή δεν φορτώθηκε`	Το autoSave και οι μαζικές αποθηκεύσεις την παρακάμπτουν με LOAD_FAILED· μόνο ένα ρητό save() την αντικαθιστά.
`Το component αποπροσαρτάται κατά την αποθήκευση`	Η αποθήκευση που ζητήθηκε ολοκληρώνεται· οι μεταγενέστερες εγγραφές στο καταστραμμένο store αγνοούνται.
`Η αποθήκευση δεν είναι διαθέσιμη`	Το store τρέχει στη μνήμη, το status().available είναι false και οι αποθηκεύσεις απορρίπτονται.
`Ένας προσαρμογέας κολλάει`	Η λειτουργία λήγει μετά από operationTimeoutMs και η επόμενη εργασία περιμένει να τελειώσει ο προσαρμογέας.
`Πάρα πολλή εκκρεμής εργασία`	Οι νέες λειτουργίες απορρίπτονται με QUEUE_FULL αντί να μεγαλώνουν χωρίς όριο.

Οι λειτουργίες ενός store δεν επικαλύπτονται ποτέ. Μια αποθήκευση που ξεκινά ενώ περιμένει άλλη παίρνει την πιο πρόσφατη τιμή, οπότε η αποθήκευση σε κάθε αλλαγή γράφει την τελευταία κατάσταση χωρίς να γεμίζει την ουρά.

useDraft.set('A');
const first = useDraft.save(); // writes "A"
useDraft.set('B');
const second = useDraft.save(); // waits in the queue
useDraft.set('C');
const third = useDraft.save(); // joins the waiting save

await Promise.all([first, second, third]); // ['A', 'C', 'C'] — two writes

Δοκιμάστε το

Επιβραδύνετε την αποθήκευση, κάντε τις εγγραφές να αποτυγχάνουν ή αφαιρέστε εντελώς την αποθήκευση.

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

Καθυστέρησηlatency
Αποτυχημένες εγγραφέςfailWrites
Αποθήκευση μη διαθέσιμηunavailable

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

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

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

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) => [`Αποθηκεύτηκε: ${JSON.stringify(value)}`, ...list]),
      (reason) => setResults((list) => [`Απέτυχε: ${reason.code ?? reason.message}`, ...list]),
    );

  return (
    <main>
      <label>
        Σημείωση
        <input value={note} onChange={(event) => useNote.set(event.target.value)} />
      </label>
      <div className="actions">
        <button onClick={save}>Αποθήκευση</button>
        <button
          onClick={() => {
            save();
            save();
            save();
          }}
        >
          Αποθήκευση τρεις φορές
        </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>Αποτελέσματα</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('Ο δίσκος είναι γεμάτος');
    records.set(key, value);
  },
  async removeItem(key) {
    await wait();
    records.delete(key);
  },
};

Όταν αποτυγχάνει η φόρτωση

Το restateManager.ready απορρίπτεται με BULK_OPERATION_FAILED και απαριθμεί κάθε store που απέτυχε. Μέχρι να φορτωθεί εκείνη η εγγραφή, τα autoSave και saveAll δεν την αντικαθιστούν και αναφέρουν LOAD_FAILED.

Δοκιμάστε ξανά με initialize() για να κρατήσετε τις αλλαγές και να τις αποθηκεύσετε, καλέστε restore() για να τις απορρίψετε, ή save() για να αντικαταστήσετε σκόπιμα την εγγραφή.

try {
  await restateManager.ready;
} catch (error) {
  // BULK_OPERATION_FAILED: one entry per store that could not load.
  for (const { store, error: cause } of error.failures) {
    console.error(store.key, cause.code);
  }
}

Αποθήκευση και κλείσιμο

Μια αποθήκευση που ζητήθηκε πριν από την αποπροσάρτηση ολοκληρώνεται ούτως ή άλλως, οπότε ο χειριστής «Αποθήκευση και κλείσιμο» δεν χρειάζεται να περιμένει.

function Document({ onClose }) {
  const useDraft = useRestateScope((scope) => persistedRestate('', { scope, key: 'draft' }));

  const saveAndClose = () => {
    useDraft.save(); // finishes even after this component unmounts
    onClose();
  };
  // …
}

Η αποθήκευση δεν είναι διαθέσιμη

Η απόδοση στον διακομιστή και η αποθήκευση που μπλοκάρει το πρόγραμμα περιήγησης δεν είναι σφάλματα εκκίνησης. Ελέγξτε το available για να πείτε στους χρήστες ότι οι αλλαγές μένουν μόνο στη μνήμη.

const { available } = useDraft.status();

if (!available) {
  // Server rendering or blocked browser storage: the store works in memory
  // and save() rejects with STORAGE_UNAVAILABLE.
  showNotice('Changes are kept until you close this tab.');
}

Επικύρωση και μεταφορά αποθηκευμένων δεδομένων

Τα version, migrate και validate σας προστατεύουν από παλιές ή κατεστραμμένες εγγραφές. Το validate εκτελείται πριν από την αποθήκευση και μετά την ανάκτηση ή τη μεταφορά.

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

const useSettings = persistedRestate(
  { theme: 'system' },
  {
    key: 'settings',
    version: 2,
    migrate(value, from, to) {
      if (from === 1 && to === 2 && typeof value?.darkMode === 'boolean') {
        return { theme: value.darkMode ? 'dark' : 'light' };
      }
      throw new Error('Unsupported stored version');
    },
    validate: (value) => ['system', 'light', 'dark'].includes(value?.theme),
  },
);

Δική σας αποθήκευση

Κάνει οποιοδήποτε αντικείμενο με getItem, setItem και removeItem. Οι μέθοδοι μπορούν να επιστρέφουν τιμές ή Promise· το isAvailable είναι προαιρετικό.

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

const sessionStorageAdapter = {
  isAvailable: () => typeof sessionStorage !== 'undefined',
  getItem: (key) => sessionStorage.getItem(key),
  setItem: (key, value) => sessionStorage.setItem(key, value),
  removeItem: (key) => sessionStorage.removeItem(key),
};

export const useFilters = persistedRestate(
  { query: '' },
  {
    key: 'filters',
    storage: sessionStorageAdapter,
  },
);

Όρια και χρονικά όρια

Ορίστε πόσο μπορεί να διαρκέσει μια λειτουργία, πόσες μπορούν να περιμένουν και πόσο μεγάλη μπορεί να είναι μια τιμή.

persistedRestate(value, {
  key: 'draft',
  operationTimeoutMs: 10_000, // default 30000
  maxPendingOperations: 64, // default 256
  maxStorageCharacters: 1_000_000,
});

Κωδικοί σφάλματος

Τα σφάλματα που δημιουργεί το restate έχουν name RestateError, code και, στα αποθηκευμένα stores, key. Οι προσαρμογείς αποθήκευσης και τα callbacks σας μπορούν να απορρίψουν με δικά τους σφάλματα.

Κωδικός	Σημασία
`BULK_OPERATION_FAILED`	Μια μαζική κλήση όπως το restateManager.ready ή το saveAll είχε αποτυχίες· δείτε το error.failures.
`INDEXEDDB_ABORTED`	Μια συναλλαγή IndexedDB ματαιώθηκε.
`INDEXEDDB_BLOCKED`	Το άνοιγμα της βάσης δεδομένων μπλοκαρίστηκε από σύνδεση σε άλλη καρτέλα.
`INDEXEDDB_CONNECTION_CLOSING`	Η σύνδεση με τη βάση δεδομένων έκλεινε όταν ξεκίνησε το αίτημα.
`INDEXEDDB_OPEN_FAILED`	Δεν ήταν δυνατό να ανοίξει η βάση δεδομένων.
`INDEXEDDB_REQUEST_FAILED`	Ένα αίτημα IndexedDB απέτυχε.
`INDEXEDDB_STORE_MISSING`	Από την ήδη υπάρχουσα βάση δεδομένων λείπει το object store.
`INVALID_STORAGE_RECORD`	Η αποθηκευμένη εγγραφή δεν είναι έγκυρη εγγραφή restate.
`INVALID_STORED_VALUE`	Η τιμή δεν πέρασε το validate.
`LIFECYCLE_LIMIT`	Ένας updater ξεκινούσε και σταματούσε επανειλημμένα.
`LOAD_FAILED`	Η εγγραφή δεν φορτώθηκε, οπότε η αυτόματη ή μαζική αποθήκευση δεν την αντικατέστησε.
`MMKV_UNAVAILABLE`	Δεν φορτώθηκε το react-native-mmkv.
`MULTIPLE_ERRORS`	Πολλά callbacks απέτυχαν σε μία λειτουργία· δείτε το error.errors.
`NOTIFICATION_LIMIT`	Οι observers προγραμμάτιζαν συνεχώς αλλαγές σε βρόχο.
`OBSERVER_ERROR`	Ένας listener ή ένα callback κύκλου ζωής πέταξε σφάλμα.
`OPERATION_ABORTED`	Μια λειτουργία αποθήκευσης ακυρώθηκε.
`QUEUE_FULL`	Περίμεναν περισσότερες λειτουργίες από όσες επιτρέπει το maxPendingOperations.
`REENTRANT_SETTER`	Ένας updater κατάστασης προσπάθησε να αλλάξει το ίδιο store ενώ εκτελούνταν.
`SCOPE_DESTROYED`	Ένα καταστραμμένο scope χρησιμοποιήθηκε για τη δημιουργία stores.
`SEQUENCE_EXHAUSTED`	Μια εσωτερική ακολουθία εξάντλησε τα αναγνωριστικά της.
`STORAGE_BLOCKED`	Μια προηγούμενη κλήση του προσαρμογέα δεν ολοκληρώθηκε μετά από λήξη χρόνου ή ακύρωση.
`STORAGE_TIMEOUT`	Μια λειτουργία διήρκεσε περισσότερο από operationTimeoutMs.
`STORAGE_UNAVAILABLE`	Η αποθήκευση δεν μπορεί να χρησιμοποιηθεί εδώ· το store συνεχίζει να τρέχει στη μνήμη.
`STORAGE_VALUE_TOO_LARGE`	Η κωδικοποιημένη τιμή υπερβαίνει το maxStorageCharacters.
`STORAGE_VERSION_MISMATCH`	Η εγγραφή έχει διαφορετική έκδοση και καμία συνάρτηση migrate δεν τη χειρίζεται.
`STORE_DESTROYED`	Έγινε συνδρομή σε καταστραμμένο store ή ζητήθηκε από αυτό να χρησιμοποιήσει αποθήκευση.

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