@lonewolfspace/storage-manager-ts/README.md

A universal browser storage manager with optional AES encryption support for localStorage, sessionStorage, and cookies.

# Storage Manager for Browser-Based JavaScript Frameworks

A universal browser and server storage manager for Next.js projects with support for `localStorage`, `sessionStorage`, and `cookies`, with optional AES encryption.

---

## 📦 Installation

```bash
npm install @lonewolfspace/storage-manager-ts
# or
yarn add @lonewolfspace/storage-manager-ts
```

---

## ✨ Features

- 🔐 Optional AES encryption support
- 🧱 Unified API for `localStorage`, `sessionStorage`, and `cookies`
- ✅ TypeScript support (Syntactic Sugar)
- ✅ Safe for use in client components
- 📦 Cookie operations based on `js-cookie`
- 📄 Modular import and usage flexibility
- 🌐 Support for **server-side cookie storage** in Next.js API routes and Server Actions

---

## 🔧 Configuration

### Client-side Configuration

```ts
import { StorageManagerConfig } from "@lonewolfspace/storage-manager-ts";

StorageManagerConfig.configureClient({
  encryption: true,
  keyPrefix: "secure_", // This option is under development 🚧
  secretKey: "your-128bit-secret-key", // Load from .env 🔐 (for Nextjs make sure to use "NEXT_PUBLIC_" prefix)
});
```

### Server-side Configuration

```ts
import { StorageManagerConfig } from "@lonewolfspace/storage-manager-ts";

StorageManagerConfig.configureServer({
  encryption: true,
  keyPrefix: "secure_", // This option is under development 🚧
  secretKey: "your-128bit-secret-key", // Load from .env 🔐 
});
```

---

## 🔐 Set Secret Key for Encryption (Optional)

```ts
StorageManager.local.setSecretKey("your-secret-key");
StorageManager.session.setSecretKey("your-secret-key");
StorageManager.cookie.setSecretKey("your-secret-key");
```

> ⚠️ If you skip setting a secret key, values will be stored in plain text.

---

## 💾 Usage Examples

### 📦 LocalStorage Example

```ts
StorageManager.local.setItem("key", "value");
const value = StorageManager.local.getItem("key");
StorageManager.local.removeItem("key");
```

---

### 🗂 SessionStorage Example

```ts
StorageManager.session.setItem("sessionKey", "sessionValue");
const value = StorageManager.session.getItem("sessionKey");
StorageManager.session.removeItem("sessionKey");
```

---

### 🍪 Cookie Example (Client-side Only)

```ts
StorageManager.cookie.setCookie("cookieKey", "cookieValue", {
  path: "/",
  maxAge: 60 * 60 * 24, // 1 day
});

const cookie = StorageManager.cookie.getCookie("cookieKey");
StorageManager.cookie.deleteCookie("cookieKey");
```

---

### ⚙️ Use in Next.js Client Components

```tsx
"use client";

import { StorageManager } from "@lonewolfspace/storage-manager-ts";

StorageManager.local.setItem("theme", "dark");
const theme = StorageManager.local.getItem("theme");
```

---

## 🧩 Modular Import

```ts
import {
  StorageManagerConfig,
  ClientLocalStorageManager,
  ClientSessionStorageManager,
  ClientCookieManager,
} from "@lonewolfspace/storage-manager-ts";

ClientLocalStorageManager.setItem("foo", "bar");
ClientSessionStorageManager.setItem("foo", "bar");
ClientCookieManager.setCookie("foo", "bar");
```

---

## 🌐 Server-side Cookie Storage

### ✅ API Route Example

```ts
// app/api/cookie/route.ts

import { StorageManagerConfig } from "@lonewolfspace/storage-manager-ts";
import { ServerCookieManager } from "@lonewolfspace/storage-manager-ts/server";
import { redirect } from "next/navigation";

StorageManagerConfig.configureServer({
  encryption: true,
  keyPrefix: "secret_",
  secretKey: "0000000000000000",
});

export async function GET() {
  await ServerCookieManager.setCookie("server_cookie", "Hello World");
  redirect("/");
}
```

### ✅ Server Action Example

```ts
"use server";

import { ServerCookieManager } from "@lonewolfspace/storage-manager-ts/server";

export const store_cookie = async () => {
  await ServerCookieManager.setCookie("server_cookie", "Hello World", {
    maxAge: 10,
  });
};
```

Then use this with form actions

### ✅ Usage in `layout.tsx`

```ts
import { StorageManagerConfig } from "@lonewolfspace/storage-manager-ts";
import { ServerCookieManager } from "@lonewolfspace/storage-manager-ts/server";

export default async function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  StorageManagerConfig.configureServer({
    encryption: true,
    keyPrefix: "secret_",
    secretKey: "0000000000000000", 
  });

  return <>...</>;
}
```

---

## 🧪 Client Demo Page Example

```tsx
"use client";
import React, { useEffect, useState } from "react";
import {
  StorageManagerConfig,
  ClientLocalStorageManager,
  ClientSessionStorageManager,
  ClientCookieManager,
} from "@lonewolfspace/storage-manager-ts";

const StoragePage = () => {
  StorageManagerConfig.configureClient({
    encryption: false,
    keyPrefix: "secret_",
    secretKey: "0000000000000000",
  });

  const [message, setMessage] = useState("");

  useEffect(() => {
    const local = ClientLocalStorageManager.getItem("greeting");
    const session = ClientSessionStorageManager.getItem("session");
    const cookie = ClientCookieManager.getCookie("client_cookie");

    console.log("LocalStorage:", local);
    console.log("SessionStorage:", session);
    console.log("Client Cookie:", cookie);
  }, []);

  return (
    <div className="p-4 space-y-4">
      <h1 className="text-xl font-bold">Storage Test (Client)</h1>

      <button
        onClick={() => {
          ClientLocalStorageManager.setItem("greeting", "Hello Local!");
          setMessage("Stored in localStorage");
        }}
        className="px-4 py-2 bg-blue-500 text-white rounded"
      >
        Set LocalStorage
      </button>

      <button
        onClick={() => {
          ClientSessionStorageManager.setItem("session", "Hello Session!");
          setMessage("Stored in sessionStorage");
        }}
        className="px-4 py-2 bg-green-500 text-white rounded"
      >
        Set SessionStorage
      </button>

      <button
        onClick={() => {
          ClientCookieManager.setCookie("client_cookie", "Hello Cookie!", {
            expires: 1,
          });
          setMessage("Stored in client cookies");
        }}
        className="px-4 py-2 bg-purple-500 text-white rounded"
      >
        Set Client Cookie
      </button>

      <div className="text-gray-700">{message}</div>
    </div>
  );
};

export default StoragePage;
```

---

## 🧾 API Reference

### `StorageManager.local` / `StorageManager.session`

| Method                | Description                 |
| --------------------- | --------------------------- |
| `setSecretKey(key)`   | Sets the AES encryption key |
| `setItem(key, value)` | Stores the value            |
| `getItem(key)`        | Retrieves the value         |
| `removeItem(key)`     | Deletes the key             |

### `StorageManager.cookie`

| Method                            | Description                 |
| --------------------------------- | --------------------------- |
| `setSecretKey(key)`               | Sets the AES encryption key |
| `setCookie(key, value, options?)` | Sets a cookie               |
| `getCookie(key)`                  | Gets a cookie value         |
| `deleteCookie(key, options?)`     | Deletes the cookie          |

### `ServerCookieManager`

| Method                            | Description                   |
| --------------------------------- | ----------------------------- |
| `setCookie(key, value, options?)` | Sets a cookie on the server   |
| `getCookie(key)`                  | Gets a cookie from the server |
| `deleteCookie(key, options?)`     | Deletes a server cookie       |

---

## 📄 License

MIT © [Manas Saha Roy](mailto:contact@lonewolfspace.com)