npm package: @slothkit/storage
Description: Enhanced localStorage with expiration, encryption, and compression.
Author: Michael Chen
Latest version: 3.0.0

![NPM Version](https://img.shields.io/npm/v/%40slothkit%2Fstorage)
![GitHub last commit](https://img.shields.io/github/last-commit/slothkit/storage)
![NPM Downloads](https://img.shields.io/npm/d18m/%40slothkit%2Fstorage)

# Storage Manager

The Storage Manager is a utility library that extends the functionality of the browser's `localStorage`, adding support for expiration management, data encryption, and data compression.

[English](README.md) | [中文](README_CN.md)

## Features

- **Expiration Management**: Automatically manage the expiration time of stored data.
- **Encryption**: Protect your stored data with encryption.
- **Compression**: Reduce the size of stored data.

## Installation

Install the Storage Manager using npm:

```bash
npm install @slothkit/storage
```

## Usage

### Initialization

Before using the Storage Manager, you need to initialize it with optional global configuration.

```javascript
import { init } from '@slothkit/storage'

init({
  // Custom encryptor, if not configured, the built-in encryptor will be used
  encryptor: {
    encrypt: yourEncryptFunction,
    decrypt: yourDecryptFunction
  },
  // Whether to encrypt all data
  encrypt: true,
  // Whether to compress all data
  compress: true
})
```

You can alse import by this way:

```javascript
import { storage } from '@slothkit/storage'
storage.init({/** your config */})
```

### Saving Data

You can save data in `localStorage` with optional configuration for encryption, compression, and expiration time.

```javascript
import { set } from '@slothkit/storage'

// Expires in 1 hour, and encrypts, compresses the data
set('myKey', 'myValue', { encrypt: true, compress: true, ttl: 3600 })

// Expires in 1s
set('myKey2', 'myValue2', { expires: Date.now() + 1 })
```

### Retrieving Data

Retrieve data from `localStorage`, automatically handling encryption, compression, and expiration.

```javascript
import { get } from '@slothkit/storage'

// If the data has expired, you will get null
const value = get('myKey')
```

### Removing Items

Remove items from `localStorage`.

```javascript
import { remove } from '@slothkit/storage'

remove('myKey')
```

### Flushing Expired Items

Remove all expired items from `localStorage`. You can also force remove all items with expiration times.

```javascript
import { flush } from '@slothkit/storage'

// Removes only expired items
flush()

// Removes all items with expiration times, regardless of whether they have expired or not
flush(true)
```

### Clearing All Items

Clear all items from `localStorage`.

```javascript
import { clear } from '@slothkit/storage'

clear()
```

### Version Control

You can set the version of the storage, and the storage manager will automatically clear all items if the version changes.

```javascript
import { init } from '@slothkit/storage'

init({
  version: 1
})
```

## Using with Next.js (SSR)

- In the browser the library uses `window.localStorage` to persist data (this means data is scoped to the browser profile/origin and is typically considered the current user's local data).
- On the server (for example Next.js SSR/Server-side environments) there is no `window`; the library uses a no-op fallback: it does not persist data and does not share data between server processes or requests. This ensures importing the library on the server does not throw and prevents accidentally sharing user data between requests.

Short recommendation: For most Next.js use cases, keeping the default no-op server fallback is the safest option; delegate real persistence to browser localStorage (client-side) or a backend store with per-user isolation.

## API

### `init(config: GlobalConfig = {})`

Initialize the Storage Manager with global configuration.

- `config`: Global configuration object.
  - `encryptor`: Object containing `encrypt` and `decrypt` functions.
  - `encrypt`: Boolean indicating whether to enable encryption by default.
  - `compress`: Boolean indicating whether to enable compression by default.
  - `version`: Storage version number.

### `set<T = any>(key: string, value: T, config: StorageConfig = {})`

Save data in `localStorage`.

- `key`: The key for the item.
- `value`: The value to store.
- `config`: Configuration object.
  - `encrypt`: Boolean indicating whether to encrypt the item.
  - `compress`: Boolean indicating whether to compress the item.
  - `ttl`: Time to live in seconds.
  - `expires`: Expiration timestamp.

### `get<T = any>(key: string): T | null`

Retrieve data from `localStorage`.

- `key`: The key for the item.

### `remove(key: string)`

Remove an item from `localStorage`.

- `key`: The key for the item.

### `flush(force: boolean = false)`

Remove expired items from `localStorage`.

- `force`: Boolean indicating whether to force remove all items with expiration times.

### `clear()`

Clear all items from `localStorage`.

### `getExp(key: string): number | void | null`
Get the expiration timestamp of an item.

- `key`: The key for the item.

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.