restate / v1.0.0

Patikimas iš esmės

Ką restate garantuoja, kai saugykla lėta, sugenda ar jos nėra, ir kaip skaityti jo pranešamas klaidas.

Šiame puslapyje

Garantijos Išsaugojimai eilės tvarka Išbandykite Kai įkėlimas nepavyksta Išsaugoti ir uždaryti Saugykla nepasiekiama Išsaugotų duomenų patikra ir perkėlimas Sava saugykla Ribos ir laiko limitai Klaidų kodai

Garantijos

Šis elgesys yra 1.0 sutarties dalis ir yra padengtas paketo testais.

Situacija	Ką daro restate
`Keli išsaugojimai iš eilės`	Vykdo juos eilės tvarka kiekvienam store; eilėje laukiantis išsaugojimas įrašo naujausią reikšmę.
`Įrašas neįsikėlė`	autoSave ir masiniai išsaugojimai jį praleidžia su LOAD_FAILED; jį pakeičia tik aiškus save().
`Komponentas atjungiamas saugant`	Paprašytas išsaugojimas baigiamas; vėlesni įrašymai į sunaikintą store ignoruojami.
`Saugykla nepasiekiama`	store veikia atmintyje, status().available yra false, o išsaugojimai atmetami.
`Adapteris užstringa`	Operacijai baigiasi laikas po operationTimeoutMs, o vėlesnis darbas laukia, kol adapteris baigs.
`Per daug laukiančio darbo`	Naujos operacijos atmetamos su QUEUE_FULL, užuot be ribų augusios.

Išsaugojimai eilės tvarka

Vieno store operacijos niekada nepersidengia. Išsaugojimas, prasidėjęs kol laukia kitas, paima naujausią reikšmę, todėl saugant po kiekvieno pakeitimo įrašoma paskutinė būsena neužpildant eilės.

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

Išbandykite

Sulėtinkite saugyklą, padarykite, kad įrašymai nepavyktų, arba visai pašalinkite saugyklą.

ValdiklisNe pavyzdžio kodo dalis. Reikšmės į pavyzdį patenka kaip props.

Delsalatency
Nepavykstantys įrašymaifailWrites
Saugykla nepasiekiamaunavailable

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

Ruošiamas pavyzdys…

Gyviems pavyzdžiams reikia JavaScript. Žemiau esantį kodą galite skaityti tokį, koks yra.

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) => [`Išsaugota: ${JSON.stringify(value)}`, ...list]),
      (reason) => setResults((list) => [`Nepavyko: ${reason.code ?? reason.message}`, ...list]),
    );

  return (
    <main>
      <label>
        Pastaba
        <input value={note} onChange={(event) => useNote.set(event.target.value)} />
      </label>
      <div className="actions">
        <button onClick={save}>Išsaugoti</button>
        <button
          onClick={() => {
            save();
            save();
            save();
          }}
        >
          Išsaugoti tris kartus
        </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>Rezultatai</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('Diskas pilnas');
    records.set(key, value);
  },
  async removeItem(key) {
    await wait();
    records.delete(key);
  },
};

Kai įkėlimas nepavyksta

restateManager.ready atmetamas su BULK_OPERATION_FAILED ir išvardija kiekvieną nepavykusį store. Kol tas įrašas neįsikels, autoSave ir saveAll jo nepakeis ir praneš LOAD_FAILED.

Bandykite dar kartą su initialize(), kad išlaikytumėte pakeitimus ir juos išsaugotumėte, iškvieskite restore(), kad juos atmestumėte, arba save(), kad sąmoningai perrašytumėte įrašą.

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

Išsaugoti ir uždaryti

Prieš atjungimą paprašytas išsaugojimas vis tiek baigiamas, todėl „Išsaugoti ir uždaryti“ apdorojimo funkcijai nereikia laukti.

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

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

Saugykla nepasiekiama

Serverio atvaizdavimas ir naršyklės užblokuota saugykla nėra paleidimo klaidos. Patikrinkite available, kad praneštumėte naudotojams, jog pakeitimai lieka tik atmintyje.

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

Išsaugotų duomenų patikra ir perkėlimas

version, migrate ir validate apsaugo jus nuo senų ar sugadintų įrašų. validate vykdoma prieš išsaugojimą ir po atkūrimo ar perkėlimo.

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),
  },
);

Sava saugykla

Tinka bet kuris objektas su getItem, setItem ir removeItem. Metodai gali grąžinti reikšmes arba Promise; isAvailable neprivalomas.

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,
  },
);

Ribos ir laiko limitai

Nustatykite, kiek gali trukti operacija, kiek jų gali laukti ir kokia didelė gali būti reikšmė.

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

Klaidų kodai

restate sukurtų klaidų name yra RestateError, jos turi code, o išsaugotų store atveju ir key. Saugyklos adapteriai ir jūsų callback gali atmesti savo klaidomis.

Kodas	Reikšmė
`BULK_OPERATION_FAILED`	Masiniame kvietime, pvz., restateManager.ready ar saveAll, buvo nesėkmių; žr. error.failures.
`INDEXEDDB_ABORTED`	IndexedDB transakcija nutraukta.
`INDEXEDDB_BLOCKED`	Duomenų bazės atidarymą užblokavo ryšys kitame skirtuke.
`INDEXEDDB_CONNECTION_CLOSING`	Užklausai prasidedant duomenų bazės ryšys buvo uždaromas.
`INDEXEDDB_OPEN_FAILED`	Duomenų bazės atidaryti nepavyko.
`INDEXEDDB_REQUEST_FAILED`	IndexedDB užklausa nepavyko.
`INDEXEDDB_STORE_MISSING`	Jau sukurtoje duomenų bazėje trūksta object store.
`INVALID_STORAGE_RECORD`	Išsaugotas įrašas nėra galiojantis restate įrašas.
`INVALID_STORED_VALUE`	Reikšmė neperėjo validate.
`LIFECYCLE_LIMIT`	updater vis paleidžiamas ir stabdomas.
`LOAD_FAILED`	Įrašo įkelti nepavyko, todėl automatinis ar masinis išsaugojimas jo nepakeitė.
`MMKV_UNAVAILABLE`	react-native-mmkv įkelti nepavyko.
`MULTIPLE_ERRORS`	Vienoje operacijoje nepavyko keli callback; žr. error.errors.
`NOTIFICATION_LIMIT`	Stebėtojai cikle vis planavo pakeitimus.
`OBSERVER_ERROR`	listener ar gyvavimo ciklo callback išmetė klaidą.
`OPERATION_ABORTED`	Saugyklos operacija atšaukta.
`QUEUE_FULL`	Laukė daugiau operacijų, nei leidžia maxPendingOperations.
`REENTRANT_SETTER`	Būsenos updater vykdymo metu bandė pakeisti tą patį store.
`SCOPE_DESTROYED`	store kurti buvo panaudotas sunaikintas scope.
`SEQUENCE_EXHAUSTED`	Vidinei sekai baigėsi identifikatoriai.
`STORAGE_BLOCKED`	Ankstesnis adapterio kvietimas nesibaigė po laiko limito ar atšaukimo.
`STORAGE_TIMEOUT`	Operacija truko ilgiau nei operationTimeoutMs.
`STORAGE_UNAVAILABLE`	Čia saugyklos naudoti negalima; store toliau veikia atmintyje.
`STORAGE_VALUE_TOO_LARGE`	Užkoduota reikšmė viršija maxStorageCharacters.
`STORAGE_VERSION_MISMATCH`	Įrašo versija kita, ir jos neapdoroja jokia migrate funkcija.
`STORE_DESTROYED`	Sunaikintas store buvo prenumeruotas arba paprašytas naudoti saugyklą.

Parašyta restate 1.0 API