npm package: @react-solutions/vault
Description: A storage library for react
Author: React Solutions
Latest version: 0.0.5

# @react-solutions/vault

<div align="center">

[![npm version](https://img.shields.io/npm/v/@react-solutions/vault.svg?color=blue&style=for-the-badge)](https://www.npmjs.com/package/@react-solutions/vault)
[![npm downloads](https://img.shields.io/npm/dm/@react-solutions/vault.svg?color=green&style=for-the-badge)](https://www.npmjs.com/package/@react-solutions/vault)
[![bundle size](https://img.shields.io/bundlephobia/minzip/@react-solutions/vault?color=orange&style=for-the-badge)](https://bundlephobia.com/package/@react-solutions/vault)

</div>
A powerful, lightweight React library providing secure, encrypted storage utilities for localStorage and sessionStorage convenient state management, automatic loading and error handling, and full TypeScript support. Use it to safely persist sensitive user data in your apps with an easy-to-use API and React hooks.

## 📦 Installation

```bash
npm install @react-solutions/vault
```

## 🚀 Features

- 🔒 **Encrypted Storage** - AES-GCM encryption for both `localStorage` and `sessionStorage`
- 🗝️ **Custom Encryption Keys** - Easily configure passphrase, salt, namespace for isolation
- ⏳ **TTL (Expiration)** - Set expiration and auto-removal for any value
- 🔄 **Atomic Updates** - Support for functional updates (like React setState)
- 🚀 **Full TypeScript Support** - Strict types and intellisense everywhere
- 💾 **Persistent + Session** - Choose persistent (`localStorage`) or session-based (`sessionStorage`) storage
- 🧼 **Clear & Remove** - One-call clear all/individual keys
- 🕵️ **Existence Check** - Easily check if a key exists
- 🔍 **Auto JSON Handling** - Transparent serialization and deserialization
- ⚡ **Ultra Lightweight** - No dependencies, tree-shakable, and small bundle size

## 📚 Quick Start

### 🛠 Usage

First, import the utilities you need:

```ts
import {
  setItem,
  getItem,
  setSession,
  getSession,
  updateItem,
  updateSession,
  removeItem,
  removeSession,
  clear,
  clearSession,
  hasItem,
  hasSession,
  useGetItem,
  useGetSession
} from "@react-solutions/vault";
```

#### Reactive Hooks

Use `useGetItem` or `useGetSession` to subscribe to storage changes. The component will re-render whenever the storage key changes.

```tsx
import { useGetItem, setItem } from "@react-solutions/vault";

function MyComponent() {
  // Automatically updates when "user" changes in localStorage
  const user = useGetItem("user"); 

  const save = () => {
    setItem("user", { name: "Alice" }, { ttl: 3600 });
  };

  return (
    <div>
      <p>User: {user?.name}</p>
      <button onClick={save}>Save User</button>
    </div>
  );
}
```

#### Standalone API Usage

##### setItem(key, value, options?)

Save a value to encrypted localStorage. Optionally set a TTL (expiration in seconds).

```ts
setItem("user", { name: "Alice" }, { ttl: 3600 });
// After 1 hour, the entry will be auto-deleted
```

##### getItem<T = any>(key, options?)

Read and decrypt a value from localStorage. Returns a Promise.

```ts
const user = await getItem("user"); // { name: "Alice" } | null
```

##### updateItem(key, updater, options?)

Update a value atomically (updater can be a function or value).

```ts
updateItem("user", (prev) => ({ ...prev, age: 30 }));
```

##### removeItem(key, options?)

Remove an item from localStorage.

```ts
removeItem("user");
```

##### hasItem(key, options?)

Check if a key exists and isn't expired.

```ts
const exists = hasItem("user"); // boolean
```

##### clear(options?)

Clear all encrypted localStorage in the current namespace.

```ts
clear();
```

---

##### setSession(key, value, options?)

Save a value to encrypted sessionStorage.

```ts
setSession("sessionData", { temp: true });
```

##### getSession<T = any>(key, options?)

Read and decrypt a value from sessionStorage. Returns a Promise.

```ts
const session = await getSession("sessionData");
```

##### updateSession(key, updater, options?)

Update a session value.

```ts
updateSession("sessionData", (prev) => ({ ...prev, lastSeen: Date.now() }));
```

##### removeSession(key, options?)

Delete a session value.

```ts
removeSession("sessionData");
```

##### hasSession(key, options?)

Check if a session key exists and isn't expired.

```ts
const active = hasSession("sessionData");
```

##### clearSession(options?)

Clear all encrypted sessionStorage in the current namespace.

```ts
clearSession();
```

---

#### ⚙️ Configuration

You can configure global settings like passphrase, salt, and namespace.

```ts
import { configureLocal, configureSession } from "@react-solutions/vault";

configureLocal({
  passphrase: "my-secret-phrase",
  salt: "custom-salt",
  namespace: "my-app"
});

configureSession({
  namespace: "my-app-session"
});
```

#### 🔑 Example: Custom Encryption Settings per Call

```ts
setItem(
  "sensitive",
  { token: "123" },
  { passphrase: "mysecret", salt: "mysalt", namespace: "secure" }
);
```

#### ⚡ Example: Using Types

```ts
type User = { id: string; name: string };
const user = await getItem<User>("user");
```

---

## 📝 TypeScript Support

This package is written in TypeScript and includes full type definitions. All exported functions and hooks are fully typed.

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📄 License

MIT

---

Made with ❤️ for React developers