restate / v1.0.0

API reference

Every export of @kkwaenggwari/restate 1.0 with its arguments, return values and behavior.

On this page

Exports

Everything is imported from @kkwaenggwari/restate on the web and on React Native.

Export	Returns	Use it to
`restate(initial, updater \| options?)`	Store hook	Create a shared memory store.
`persistedRestate(initial, options)`	Saved store hook	Create a store that restores and saves through storage.
`useRestateScope(factory?)`	Factory result or scope	Own stores in a component; destroyed after unmount.
`createRestateScope()`	RestateScope	Own stores outside React; call destroy() when done.
`shallow(left, right)`	boolean	Compare selections one level deep.
`batch(callback)`	Callback result	Notify subscribers once after several changes.
`restateManager`	RestateManager	Wait for startup data and run bulk operations on global stores.
`createIndexedDBStorage(options?)`	RestateStorage	Create an IndexedDB adapter with a custom database or store name.
`createMMKVStorage(options?)`	RestateStorage	Create an MMKV adapter with your own instance or configuration.

A store is a function you call as a hook, with these methods.

Member	Description
`useStore()`	Returns the whole value and re-renders on each change.
`useStore(selector, isEqual?)`	Returns the selection; re-renders when isEqual (default Object.is) reports a change.
`get()`	Current value, without subscribing.
`set(value \| updater)`	Replace the value or compute it from the previous one. Ignored after destroy().
`reset()`	Restore the declared initial value and return it.
`subscribe(listener)`	Call listener(value, previous, event) after each change; returns an unsubscribe function.
`subscribeSelector(selector, listener, isEqual?)`	Call listener only when the selection changes.
`on(type, listener)`	Listen to events such as change, reset, save or error.
`start() / stop() / isRunning()`	Control the updater by hand.
`destroy() / isDestroyed()`	Release listeners and the updater. Later subscriptions throw STORE_DESTROYED.
`getInitial() / getServerSnapshot() / getError()`	Initial value, server snapshot and the last listener error.
`id / kind`	Unique id; memory or persistent.

persistedRestate returns a store with these additional members.

Member	Description
`ready`	Promise that settles when the automatic load finishes, even if it failed. Check status().
`save()`	Write the current value; resolves with the value actually written.
`restore()`	Read the saved value into memory.
`hasSaved()`	Whether a saved record exists.
`clearStorage()`	Delete the saved record; memory is unchanged.
`resetAndClearStorage()`	Reset memory to the initial value and delete the saved record.
`initialize()`	Load again, for example after fixing a failed record.
`status()`	Frozen status snapshot; the same object until a field changes.
`useStatus(selector?, isEqual?)`	Hook that re-renders when the status or the selected part changes.
`key / storageKey / storage`	Logical key, namespaced key and the adapter in use.

key is required. Every other option is optional.

Option	Default	Meaning
`key`	required	Logical record key.
`namespace`	"@kkwaenggwari/restate"	Prefix of the stored key; an empty string disables it.
`storage`	IndexedDB / MMKV	Adapter to use instead of the platform default.
`autoSave`	false	true saves after each change; { delayMs } waits for a pause.
`version / migrate`	1 / none	Record version and how to upgrade older records.
`validate`	none	Checks values before save and after restore or migration.
`serializer`	JSON	Custom serialize and deserialize functions.
`operationTimeoutMs`	30000	Time limit for one storage operation.
`maxPendingOperations`	256	Pending operations allowed, including the active one.
`maxStorageCharacters`	5242880	Largest encoded value in UTF-16 code units.
`updater / managed / serverSnapshot / onError`	—	Same as restate options.

status() and useStatus() return these fields.

Field	Meaning
`ready`	The automatic load has finished.
`dirty`	Memory differs from the value last loaded, saved or restored.
`operation`	The storage operation running now, or null.
`pending`	Unsettled storage operations, including the active one.
`blocked`	An aborted or timed-out adapter call has not settled yet.
`available`	Whether storage can be used.
`error / observerError`	Last storage error; last status listener error.
`lastSavedAt / lastRestoredAt`	Epoch milliseconds of the last success, or null.

Each manager tracks the persistent stores registered with it.

Member	Description
`ready`	Waits for the stores registered at access time; rejects with BULK_OPERATION_FAILED.
`saveAll(options?) / restoreAll(options?)`	Run save or restore for every store; { concurrency } limits parallel work.
`clearStorageAll() / resetAll() / resetAllAndClearStorage()`	Clear records, reset memory, or both.
`list() / get(idOrKey) / size()`	Inspect registered stores.
`subscribe(listener) / status()`	Observe manager events and listener errors.
`destroyAll()`	Destroy every registered store.

Pass an object with these methods as storage. Every method may return a value or a Promise.

Method	Description
`getItem(key, context?)`	Return the saved string or null.
`setItem(key, value, context?)`	Store the string.
`removeItem(key, context?)`	Delete the record.
`isAvailable?()`	Synchronously report whether storage can be used.
`clear?() / close?()`	Optional clearing and cleanup.
`coordinationKey?`	Shared object for wrappers of the same backing storage.

Written for the restate 1.0 API