# localit

> Manage your Storage with ease, adding expiration dates through a simple API

Latest version **6.1.0** (published 2025-07-29) · MIT license · 0 weekly downloads

## Install

```sh
npm install localit
pnpm add localit
yarn add localit
bun add localit
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 6.1.0 |
| Published | 2025-07-29 |
| First published | 2020-04-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 11.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 17 |
| Author | Alejandro Mayol |
| Maintainers | alexmayolc |
| Keywords | JavaScript, library, localStorage, sessionStorage, cache, store, Vite, TypeScript |

## Links

- npm: https://www.npmjs.com/package/localit
- Repository: https://github.com/alexmayol/localit
- Homepage: https://github.com/alexmayol/localit#readme
- Issues: https://github.com/alexmayol/localit/issues
- npm.io page: https://npm.io/package/localit

## Alternatives

- [memory-cache](https://npm.io/package/memory-cache.md) — 795.0K weekly downloads
- [@httptoolkit/proxy-agent](https://npm.io/package/@httptoolkit/proxy-agent.md) — 11.2K weekly downloads
- [express-cache-controller](https://npm.io/package/express-cache-controller.md) — 5.3K weekly downloads
- [http-cache-middleware](https://npm.io/package/http-cache-middleware.md) — 4.5K weekly downloads
- [cache2](https://npm.io/package/cache2.md) — 1.5K weekly downloads

## Recent versions

- 6.1.0 (latest) — 2025-07-29
- 6.0.0 — 2025-07-19
- 5.1.1 — 2024-12-04
- 5.1.0 — 2024-11-30
- 5.0.0 — 2023-07-20
- 4.3.0 — 2023-07-20
- 4.2.0 — 2021-10-23
- 4.1.0 — 2021-10-23
- 4.0.0 — 2021-05-16
- 3.0.0 — 2020-12-01
- 2.1.4 — 2020-11-25
- 2.1.3 — 2020-10-20
- 2.1.2 — 2020-09-24
- 2.1.1 — 2020-08-16
- 2.1.0 — 2020-08-16
- … 6 more at https://npm.io/package/localit/versions

## README

# localit
![minzip size](https://badgen.net/bundlephobia/minzip/localit)
![dependency count](https://badgen.net/bundlephobia/dependency-count/localit)
![tree-shakeable](https://badgen.net/bundlephobia/tree-shaking/localit)


🔥 A lightweight, fully-typed wrapper around the Web Storage API (`localStorage` / `sessionStorage`) with expiration support, optional key namespacing, and change event listeners.

## ✅ Features

- Store/retrieve plain and complex values easily, no `JSON.stringify` required.
- Expiration time support, you decide how log to cache the data
- Family-based key namespacing
- Listen to changes on individual keys
- No dependencies, <1kB gzipped

---

## 📦 Install

```bash
npm i localit
# or
yarn add localit
# or
pnpm add localit
```

---

## 🚀 Usage

### Import

```ts
import { localit } from "localit";
```

---

### `set(key, value, config?)`

Store a value in storage.

```ts
localit.set("foo", { bar: 42 }, { expiration: "5m" });
localit.set("name", "User123", { family: "user" });
localit.set("list", new Set([1, 2, 3]), { type: sessionStorage });
const tomorrow = new Date();
tomorrow.setDate(tomorrow.getDate() + 1);
localit.set("lasts-a-day", { some: "data" }, { expiration: tomorrow });
```

Config options:

- `type`: `localStorage` (default) or `sessionStorage`
- `family`: string to namespace the key (stored as `family::key`)
- `expiration`: `"Xs"`, `"Xm"`, `"Xh"`, or `"Xd"`. Also accepts a `Date` object for a fixed expiration date.

---

### `get(key, config?)`

Retrieve a value.

```ts
const value = localit.get("foo");
const set = localit.get<Set<number>>("list");
```

If the value has expired, it will be removed and `null` is returned.

---

### `remove(key, config?)`

Delete a specific key.

```ts
localit.remove("foo");
```

Also, specify a family for even more control

```ts
localit.set('foo', 'bar') // Will be stored with 'foo' as key
localit.set('foo', 'baz' { family: 'bar' }) // Will be stores with 'bar::foo key

localit.remove('foo') // Will detele 'foo' but not 'bar::foo'
```

---

### `clearFamily(family, storage?)`

Remove all keys that belong to a given family.

```ts
localit.clearFamily("user");
localit.clearFamily("cache", sessionStorage); // Only delete `cache` family in sessionStorage, localStorage keys are kept intact
```

---

### `bust(storage?)`

Clear all keys from the given storage (`localStorage` by default)

```ts
localit.bust(); // clears localStorage
localit.bust(sessionStorage); // clears sessionStorage
```

---

### `on(key, callback)`

Subscribe to key changes (e.g. via `set()` or `remove()`).

```ts
localit.on("foo", (newValue) => {
  console.log("foo changed:", newValue);
});
```

Note: this is _not_ the same as the native `storage` event—it only triggers within the current context when `localit` methods are used.

---

## 🧪 Example

```ts
localit.set("cart", { count: 3 }, { expiration: "2h" });

const cart = localit.get("cart"); // { count: 3 }

localit.on("cart", (val) => {
  console.log("Cart updated:", val);
});

localit.set("cart", { count: 4 }); // logs: Cart updated: { count: 4 }
```

---

## 📚 Types

```ts
type ExpirationType =
  | `${number}s`
  | `${number}m`
  | `${number}h`
  | `${number}d`
  | Date;

type LocalitSetConfig = {
  type?: Storage;
  family?: string;
  expiration?: ExpirationType;
};

type LocalitGetConfig = {
  type?: Storage;
  family?: string;
};
```

---

## 🛠 Author

**Alejandro Mayol**  
[github.com/alexmayol](https://github.com/alexmayol)

---
_Source: https://npm.io/package/localit · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._