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 | 中文

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:

npm install @slothkit/storage

Usage

Initialization

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

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:

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.

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.

import { get } from '@slothkit/storage'

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

Removing Items

Remove items from localStorage.

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.

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.

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.

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 file for details.