Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jasonraimondi/browser-storage
An abstracted storage library for browser applications that interfaces with localStorage, sessionStorage, in-memory storage, or any custom serializer. It provides serialization capabilities with optional key prefixing for better storage management.
https://github.com/jasonraimondi/browser-storage
localstorage sessionstorage
Last synced: 3 months ago
JSON representation
An abstracted storage library for browser applications that interfaces with localStorage, sessionStorage, in-memory storage, or any custom serializer. It provides serialization capabilities with optional key prefixing for better storage management.
- Host: GitHub
- URL: https://github.com/jasonraimondi/browser-storage
- Owner: jasonraimondi
- License: mit
- Created: 2023-06-18T23:56:08.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-08-05T19:05:27.000Z (6 months ago)
- Last Synced: 2024-11-06T01:42:49.054Z (3 months ago)
- Topics: localstorage, sessionstorage
- Language: TypeScript
- Homepage: https://jsr.io/@jmondi/browser-storage
- Size: 66.4 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# @jmondi/browser-storage
An abstracted storage library for **browser** applications that interfaces with localStorage, sessionStorage, in-memory storage, or any custom serializer. It provides serialization capabilities with optional key prefixing for better storage management.
[](https://jsr.io/@jmondi/browser-storage)
[](https://jsr.io/@jmondi/browser-storage)
[](https://github.com/jasonraimondi/browser-storage)
[](https://codeclimate.com/github/jasonraimondi/browser-storage/test_coverage)
## Installation
For Node.js:
```bash
pnpx jsr add @jmondi/browser-storage
```
For Deno:
```ts
deno add @jmondi/browser-storage
```
## Usage
`LocalStorage` and `SessionStorage` are wrappers for `window.localStorage` and `window.sessionStorage`. You can add your own custom adapters to use `Cookies` or `IndexedDB` etc.
```typescript
const storage = new LocalStorage({ prefix: "myapp__" });
const LOCAL_STORAGE = storage.defineGroup({ token: "jti", current_user: "u" });
// any primitive value
LOCAL_STORAGE.token.key; // "myapp__jti
LOCAL_STORAGE.token.set("newtoken");
LOCAL_STORAGE.token.get(); // "newtoken"
LOCAL_STORAGE.token.remove();
// any serializable object
LOCAL_STORAGE.current_user.key; // "myapp__u"
LOCAL_STORAGE.current_user.set({ email: "[email protected]" });
LOCAL_STORAGE.current_user.get(); // { email: "[email protected]" }
LOCAL_STORAGE.current_user.remove();
// pop removes and returns the value
LOCAL_STORAGE.current_user.set({ email: "[email protected]" });
LOCAL_STORAGE.current_user.pop(); // { email: "[email protected]" }
LOCAL_STORAGE.current_user.get(); // null
```
Use `define` for individual single storage keys, for example:
```typescript
type UserInfo = { email: string };
const storage = new LocalStorage();
const USER_INFO_STORAGE = storage.define("user_info");
USER_INFO_STORAGE.set({ email: "[email protected]" });
USER_INFO_STORAGE.get(); // gets the latest value
USER_INFO_STORAGE.remove(); // removes the value
```
You can also define keys dynamically
```typescript
const storage = new LocalStorage();
storage.set("user2", { email: "[email protected]" });
console.log(storage.get("user2"));
```
### The LocalStorage class
Persists after closing browser
```typescript
import { LocalStorage } from "@jmondi/browser-storage";
const storage = new LocalStorage();
```
### The SessionStorage class
Resets on browser close
```typescript
import { SessionStorage } from "@jmondi/browser-storage";
const storage = new SessionStorage();
```
### Example Custom storage adapter
An example implementation of a custom adapter using `js-cookie`
```ts
import { type Adapter, BrowserStorage } from "@jmondi/browser-storage";
import Cookies from "js-cookie";
export class CookieAdapter implements Adapter {
getItem(key: string): string | null {
return Cookies.get(key) ?? null;
}
removeItem(key: string): void {
Cookies.remove(key);
}
setItem(key: string, value: string, config?: Cookies.CookieAttributes): void {
Cookies.set(key, value, config);
}
}
const COOKIE_STORAGE = new BrowserStorage({
prefix: "app_",
adapter: new CookieAdapter(),
});
COOKIE_STORAGE.defineGroup({ cookie_thing: "my-cookie-thing-name" })
COOKIE_STORAGE.cookie_thing.key; // "app_my-cookie-thing-name"
COOKIE_STORAGE.cookie_thing.set("value");
COOKIE_STORAGE.cookie_thing.get(); // "value"
```
## Configuration
Optional settings: `prefix` (key prefix), `serializer` (defaults to `JSON`).
```ts
import { BrowserStorage } from "./index.ts";
const storage = new LocalStorage({ prefix: 'app_', serializer: JSON });
```
## Custom Serializers
To create a custom serializer, implement `parse` and `stringify`.
```ts
import superjson from "superjson";
import { StorageSerializer } from "@jmondi/browser-storage";
export class SuperJsonSerializer implements StorageSerializer {
parse(value: string): T {
return superjson.parse(value);
}
stringify(value: T): string {
return superjson.stringify(value);
}
}
```