localstorage-platform
Interactive Playground
Explore the library in action without installing anything.
Live Demo: https://stackblitz.com/edit/react-fhubawn2?file=src%2FApp.js,src%2Fstyle.css
Documentation
Learn how to install, configure, and use localstorage-platform with comprehensive guides, API references, architecture, and examples.
Getting Started: https://localstorage-platform-docs.vercel.app/docs/getting-started
Documentation: https://localstorage-platform-docs.vercel.app
Why?
Every application starts small.
localStorage.setItem("user", JSON.stringify(user));
localStorage.setItem("theme", "dark");
localStorage.setItem("token", token);As the application grows, storage becomes difficult to manage.
- Keys are scattered throughout the codebase.
- Cleanup logic is duplicated.
- Related data becomes difficult to remove.
- Expired values remain forever.
- Sensitive information is stored in plain text.
- Different applications can accidentally reuse the same keys.
The browser provides storage.
It does not provide storage architecture.
localstorage-platform fills that gap.
Philosophy
Storage is more than saving data.
Every stored value should answer questions like:
- Who owns this data?
- How long should it exist?
- Should it expire?
- Should it be encrypted?
- How should it be cleaned up?
Instead of treating browser storage as random key-value pairs, this library treats it as a structured part of your application.
Features
- Namespace isolation
- Type-safe API
- Metadata for every value
- Automatic TTL expiration
- Optional AES encryption
- Group-based cleanup
- Lightweight (~2 KB ESM)
- Framework agnostic
- Zero configuration
Installation
Using pnpm
pnpm add localstorage-platformUsing npm
npm install localstorage-platformQuick Start
import {
StorageManager,
CleanupManager
} from "localstorage-platform";
const storage = new StorageManager("company-name");
const cleanup = new CleanupManager(
"company-name",
storage
);
storage.set("theme", "dark");
storage.set("user", {
id: 1,
name: "Jay"
});
const user = storage.get<{
id: number;
name: string;
}>("user");Namespace Isolation
Namespaces prevent different applications or features from using the same storage keys.
const storage = new StorageManager("company-name");
storage.set("user", user);Stored in the browser as:
company-name:userMetadata
Every stored value includes metadata.
{
"value": {
"id": 1,
"name": "Jay"
},
"meta": {
"group": "session",
"encrypt": true,
"createdAt": 171111111,
"updatedAt": 171111111,
"expiresAt": 171112111
}
}Metadata enables advanced features without changing the storage format.
Time-To-Live (TTL)
Automatically expire stored values.
storage.set(
"session",
session,
{
ttl: 60000
}
);Expired values are automatically removed when accessed.
Encryption
Encrypt only the values you choose.
Create the storage manager with a secret.
const storage = new StorageManager(
"company-name",
{
encryption: {
secret: "my-secret-key"
}
}
);Store encrypted data.
storage.set(
"token",
token,
{
encrypt: true
}
);Retrieve it normally.
const token =
storage.get<string>("token");Only the stored value is encrypted.
Metadata remains readable so TTL and cleanup continue to work.
Group-Based Cleanup
Store related values together.
storage.set(
"user",
user,
{
group: "session"
}
);
storage.set(
"token",
token,
{
group: "session"
}
);Later,
cleanup.clearGroup("session");Before
company-name:user
company-name:token
company-name:themeAfter
company-name:themeAPI
StorageManager
storage.set(
key,
value,
options
);
storage.get(key);
storage.has(key);
storage.getMetadata(key);
storage.remove(key);Metadata Options
{
group?: string;
ttl?: number;
encrypt?: boolean;
}CleanupManager
cleanup.clearGroup(group);
cleanup.clearAll();Example
const storage = new StorageManager(
"app",
{
encryption: {
secret: "secret-key"
}
}
);
storage.set(
"theme",
"dark"
);
storage.set(
"token",
"abc123",
{
group: "auth",
encrypt: true
}
);
storage.set(
"profile",
{
id: 7
},
{
group: "user"
}
);
cleanup.clearGroup("auth");Architecture
StorageManager
Responsible for:
- set
- get
- has
- getMetadata
- remove
CleanupManager
Responsible for:
- clearGroup
- clearAll
Keeping these responsibilities separate keeps the library simple and extensible.
Testing
Run the complete test suite.
pnpm test:runThe project includes automated tests for:
- Storage operations
- Metadata
- TTL
- Encryption
- Namespace isolation
- Group cleanup
- Corrupted storage handling
Current Scope
Version 1.x focuses on providing a solid storage foundation.
- Namespace isolation
- Metadata
- TTL
- Optional encryption
- Group cleanup
- Type safety
Roadmap
Future versions may include:
- Session Storage support
- IndexedDB adapter
- Memory storage adapter
- Storage drivers
- Compression
- Data migrations
- Synchronization
- React hooks
The API is designed so these features can be added without breaking existing applications.
Design Philosophy
Good software grows.
Your storage layer should grow with it.
localstorage-platform stores metadata alongside every value instead of maintaining separate registries. This keeps each stored item self-contained and allows new capabilities to be introduced without changing the storage format.
Today's features:
- Namespaces
- Metadata
- TTL
- Encryption
- Cleanup
Tomorrow's possibilities:
- Multiple storage backends
- Compression
- Migrations
- Synchronization
- Plugins
The goal is not to wrap localStorage.
The goal is to build a storage foundation that applications can rely on.
Contributing
Issues, feature requests, and pull requests are always welcome.
If you have an idea that makes browser storage simpler, safer, or more scalable, we'd love to discuss it.
License
MIT