sync-storage

sync-storage is a universal, synchronous storage solution for React web and desktop (Electron) applications. It provides a consistent API for managing web storage—whether you're using localStorage, sessionStorage, or a custom storage interface—while supporting core operations, bulk actions, JSON handling, TTL (time-to-live), and even React hooks for automated cleanup.

For more details on the underlying Web Storage API, please refer to the MDN Web Storage API documentation.

Features

• Core Storage Operations: Get, set, update, and remove individual keys.
• Bulk Operations: Filter, update, and remove multiple keys based on a predicate.
• JSON Support: Seamlessly store and retrieve objects using automatic JSON serialization.
• TTL (Time-To-Live) Support: Set expiration times for stored items.
• React Hooks: Use built-in hooks for automatic storage cleanup in your React components.
• Universal: Works with any Web Storage API–compatible storage (localStorage, sessionStorage, or custom adapters).

Installation

Install via npm:

npm install @aivron/sync-storage

Or via yarn:

yarn add @aivron/sync-storage

Usage

Importing the Library

You can import individual functions or the entire module:

// Import specific functions:
import { setStorageItem, getStorageItem } from '@aivron/sync-storage';

// Or import the entire module:
import * as storage from '@aivron/sync-storage';

Basic Storage Operations

Store a Key-Value Pair

import { setStorageItem } from '@aivron/sync-storage';

setStorageItem('userToken', 'abc123');

Retrieve a Stored Item

import { getStorageItem } from '@aivron/sync-storage';

const token = getStorageItem('userToken');
console.log(token); // Output: "abc123"

Update a Stored Item

import { updateStorageItem } from '@aivron/sync-storage';

updateStorageItem('userToken', current =>
  current ? current + '_v2' : 'defaultToken'
);

Remove a Stored Item

import { removeStorageItem } from '@aivron/sync-storage';

removeStorageItem('userToken');

Bulk Operations

Retrieve Multiple Items

For example, retrieve all keys that start with "app:":

import { getStorageItems } from '@aivron/sync-storage';

const appItems = getStorageItems(key => key.startsWith('app:'));
console.log(appItems);

Update Multiple Items

import { updateStorageItems } from '@aivron/sync-storage';

updateStorageItems(
  key => key.startsWith('app:'),
  current => (current ? current.toUpperCase() : '')
);

Remove Multiple Items

import { removeStorageKeys } from '@aivron/sync-storage';

removeStorageKeys(key => key.includes('temp'));

JSON Operations

Store a JSON Value

import { setJSONItem } from '@aivron/sync-storage';

setJSONItem('userData', { name: 'Alice', age: 30 });

Retrieve a JSON Value

import { getJSONItem } from '@aivron/sync-storage';

const userData = getJSONItem<{ name: string; age: number }>('userData');
console.log(userData);

Update a JSON Value

import { updateJSONItem } from '@aivron/sync-storage';

updateJSONItem<{ name: string; age: number }>('userData', current => ({
  ...current,
  age: (current?.age || 0) + 1,
}));

TTL (Time-To-Live) Operations

Store an Item with TTL

Store an item that expires in 1 hour:

import { setStorageItemWithTTL } from '@aivron/sync-storage';

setStorageItemWithTTL('sessionData', 'sessionValue', 3600 * 1000);

Retrieve an Item with TTL

import { getStorageItemWithTTL } from '@aivron/sync-storage';

const sessionValue = getStorageItemWithTTL('sessionData');
console.log(sessionValue);

React Hook for Storage Cleanup

Automatically remove storage keys that match a predicate when your component mounts:

import React from 'react';
import { useStorageCleanup } from '@aivron/sync-storage';

function App() {
  // Automatically remove any keys that start with "old:" when the component mounts.
  useStorageCleanup(key => key.startsWith('old:'));

  return <div>Your React Web/Desktop App</div>;
}

export default App;

MDN Documentation

This package is built in accordance with the MDN Web Storage API specification. For in-depth information on how the Web Storage API works, please review the MDN documentation linked above.

API Reference

For a detailed API reference, please consult the source code or visit the repository's documentation site.

Contributing

Contributions, bug reports, and feature requests are welcome! Please see the issues page for more details on how to contribute.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Repository

For the full source code and further documentation, visit the sync-storage GitHub repository.

Enjoy using @aivron/sync-storage as your go-to solution for synchronous web storage in React web and desktop projects! If you have any questions or need assistance, feel free to open an issue on GitHub.