@fullstackhouse/react-native-sync-storage

A synchronous storage library for React Native that provides immediate access to persisted data while maintaining async persistence in the background.

Features

• Synchronous API: Access stored data immediately without await
• Async Persistence: Background persistence to AsyncStorage
• React Integration: Built-in React Context and hooks
• Cross-Platform: Works on iOS, Android, and Web
• TypeScript Support: Fully typed with TypeScript
• Prefix Support: Namespace your storage keys
• Comprehensive Testing: 100% test coverage with Jest and Playwright

Installation

npm install @fullstackhouse/react-native-sync-storage
# or
yarn add @fullstackhouse/react-native-sync-storage

Dependencies

This library depends on @react-native-async-storage/async-storage. If you don't have it installed:

npm install @react-native-async-storage/async-storage
# or
yarn add @react-native-async-storage/async-storage

Follow the AsyncStorage installation guide for platform-specific setup.

Usage

With React Context (Recommended)

import React from 'react';
import { View, Text, TouchableOpacity } from 'react-native';
import { SyncStorageProvider, useSyncStorage } from '@fullstackhouse/react-native-sync-storage';

function MyComponent() {
  const { storage, loaded } = useSyncStorage();

  const handleSave = () => {
    // Synchronously set data
    storage.setItem('user_preference', 'dark_mode');
  };

  const handleLoad = () => {
    // Synchronously get data
    const preference = storage.getItem('user_preference');
    console.log('Preference:', preference); // 'dark_mode' or null
  };

  if (!loaded) {
    return <Text>Loading...</Text>;
  }

  return (
    <View>
      <TouchableOpacity onPress={handleSave}>
        <Text>Save Preference</Text>
      </TouchableOpacity>
      <TouchableOpacity onPress={handleLoad}>
        <Text>Load Preference</Text>
      </TouchableOpacity>
    </View>
  );
}

export default function App() {
  return (
    <SyncStorageProvider prefix="myapp_">
      <MyComponent />
    </SyncStorageProvider>
  );
}

Direct Usage

import { SyncStorage } from '@fullstackhouse/react-native-sync-storage';

const storage = new SyncStorage({ prefix: 'myapp_' });

// Initialize storage (load from AsyncStorage)
await storage.load();

// Now use synchronously
storage.setItem('key', 'value');
const value = storage.getItem('key'); // 'value'

// Multiple operations
storage.multiSet([
  ['key1', 'value1'],
  ['key2', 'value2']
]);

const values = storage.multiGet(['key1', 'key2']);
// [['key1', 'value1'], ['key2', 'value2']]

// Get all keys
const keys = storage.getAllKeys(); // ['key1', 'key2']

// Clear all data
storage.clear();

API Reference

SyncStorage Class

Constructor

new SyncStorage(options?: SyncStorageOptions)

Options:

• prefix?: string - Optional prefix for all keys

Methods

• load(): Promise<void> - Load data from AsyncStorage (call once at app start)
• getItem(key: string): string | null - Get value synchronously
• setItem(key: string, value: string): void - Set value synchronously
• removeItem(key: string): void - Remove value synchronously
• clear(): void - Clear all data synchronously
• getAllKeys(): string[] - Get all keys synchronously
• multiGet(keys: string[]): Array<[string, string | null]> - Get multiple values
• multiSet(keyValuePairs: Array<[string, string]>): void - Set multiple values
• multiRemove(keys: string[]): void - Remove multiple values
• loaded: boolean - Whether storage has been loaded from AsyncStorage

React Hooks

useSyncStorage()

const { storage, loaded } = useSyncStorage();

Returns:

• storage: SyncStorage - The storage instance
• loaded: boolean - Whether storage has been loaded

React Components

SyncStorageProvider

<SyncStorageProvider prefix?: string>
  {children}
</SyncStorageProvider>

Props:

• prefix?: string - Optional prefix for all keys
• children: ReactNode - Child components

How It Works

1. Initialization: Call storage.load() or use SyncStorageProvider to load existing data from AsyncStorage into memory
2. Synchronous Access: All read operations (getItem, multiGet, etc.) work immediately from memory
3. Async Persistence: All write operations (setItem, multiSet, etc.) update memory immediately and persist to AsyncStorage in the background
4. Error Handling: Persistence errors are logged but don't affect the synchronous operations

Platform Support

• ✅ iOS: Full support with AsyncStorage
• ✅ Android: Full support with AsyncStorage
• ✅ Web: Full support with localStorage fallback
• ✅ Expo: Full support with Expo AsyncStorage

Testing

The library includes comprehensive tests:

# Unit tests
yarn test

# Web integration tests
yarn playwright test

Contributing

We welcome contributions! Please feel free to submit a Pull Request.

Development Setup

git clone https://github.com/fullstackhouse/react-native-sync-storage.git
cd react-native-sync-storage
yarn install

# Run tests
yarn test
yarn playwright test

# Run example
yarn example ios    # or android, web

License

MIT © FullStackHouse

Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

Made with ❤️ by FullStackHouse