useParameterPersistence

Installation

pnpm dlx @docyrus/cli add @docyrus/rn-hooks-use-parameter-persistence

The module exports the useParameterPersistence hook and the helpers the Docyrus listing hooks share: resolvePersistConfig, buildPersistKey, getPersistStore, plus the PersistStateProp types. It is the engine behind the persistState option of the Docyrus listing hooks.

Overview

The hook takes a snapshot object, restores a stored copy once per storage key, and writes changes back after a debounce.

• Restore once per key. When storageKey changes (for example the user switches to another saved view), the stored overlay for the new key is restored.
• No write before restore. The first snapshot for a key never overwrites stored state before that key has been restored.
• Ordering. Declare the hook after any effect that applies a saved view, so the restored overlay lands on top of the view preset in the same commit.
• Failure tolerant. Corrupt JSON, a failing store or a serialization error is ignored.

Storage on React Native

React Native has no localStorage / sessionStorage, so storage resolves through the package's lib/storage module:

The contract is synchronous (getItem / setItem / removeItem), because the listing hooks read their state during mount. Recommended backends are expo-sqlite/kv-store (works in Expo Go) and react-native-mmkv (dev build). AsyncStorage is asynchronous and does not fit.

Mount <DocyStorageProvider> above every Docyrus listing hook. It registers the store synchronously during render, because child mount effects run before parent effects.

import Storage from 'expo-sqlite/kv-store';

import { DocyStorageProvider, type DocyKeyValueStore } from '@/lib/docyrus/storage';

const kvStore: DocyKeyValueStore = {
  getItem: key => Storage.getItemSync(key),
  setItem: (key, value) => Storage.setItemSync(key, value),
  removeItem: (key) => {
    Storage.removeItemSync(key);
  }
};

export function AppProviders({ children }: { children: React.ReactNode }) {
  return <DocyStorageProvider store={kvStore}>{children}</DocyStorageProvider>;
}

lib/storage also exports setDocyLocalStore(store | null) (register outside React), getDocyStore(kind), getInjectedDocyLocalStore() and createMemoryStore().

Usage

import { useCallback, useMemo, useState } from 'react';

import {
  buildPersistKey,
  resolvePersistConfig,
  useParameterPersistence,
  type PersistStateProp
} from '@/hooks/docyrus-native/use-parameter-persistence';

type ListParams = { search: string; sort: string };

export function useContactListParams(viewId: string | null, persistState?: PersistStateProp) {
  const [search, setSearch] = useState('');
  const [sort, setSort] = useState('name');

  const config = resolvePersistConfig(persistState);
  const storageKey = config && viewId
    ? buildPersistKey(['crm', config.key || 'contacts', viewId])
    : null;

  const snapshot = useMemo<ListParams>(() => ({ search, sort }), [search, sort]);

  const onRestore = useCallback((restored: Partial<ListParams>) => {
    if (restored.search !== undefined) setSearch(restored.search);
    if (restored.sort !== undefined) setSort(restored.sort);
  }, []);

  useParameterPersistence<ListParams>({
    enabled: Boolean(config),
    storage: config?.storage ?? 'session',
    storageKey,
    ready: viewId !== null,
    snapshot,
    onRestore
  });

  return { search, setSearch, sort, setSort };
}

API Reference

useParameterPersistence(args)

Returns void.

resolvePersistConfig(prop)

Returns: { storage: ParameterPersistenceStorage; key: string } | null. true becomes { storage: 'session', key: '' }; an object fills storage (default 'session') and key (default ''); falsy returns null.

buildPersistKey(parts)

Returns: string, e.g. docyrus:view-params:<appSlug>:<dataSourceSlug>:<viewId>.

getPersistStore(storage)

Returns: DocyKeyValueStore | null. On native a store is always resolved (see the storage table); null only if resolving throws. Shared with the saved-view hooks so every layer resolves storage the same way.

Type Exports