# @varasto/storage

> Type definitions for Varasto key-value storage

Latest version **6.0.0** (published 2026-09-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install @varasto/storage
pnpm add @varasto/storage
yarn add @varasto/storage
bun add @varasto/storage
```

## Health

**Score 70/100 (B)** — status: active.

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

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 6.0.0 |
| Published | 2026-09-05 |
| First published | 2021-02-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22.0 |
| Dependencies | 2 |
| Unpacked size | 25.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Rauli Laine |
| Maintainers | rauli |

## Links

- npm: https://www.npmjs.com/package/@varasto/storage
- Repository: https://github.com/RauliL/varasto
- Homepage: https://rauli.dev/varasto
- Issues: https://github.com/RauliL/varasto/issues
- npm.io page: https://npm.io/package/@varasto/storage

## Dependencies (2)

- [type-fest](https://npm.io/package/type-fest.md) ^5.9.0
- [is-valid-slug](https://npm.io/package/is-valid-slug.md) ^1.0.0

## Recent versions

- 6.0.0 (latest) — 2026-09-05
- 5.0.0 — 2023-10-05
- 4.1.0 — 2023-10-03
- 4.0.0 — 2023-09-30
- 3.1.2 — 2023-05-24
- 3.1.1 — 2021-10-22
- 3.1.0 — 2021-10-05
- 3.0.0 — 2021-08-13
- 2.0.0 — 2021-02-20

## README

# @varasto/storage

[![npm][npm-image]][npm-url]

Type definitions for Varasto JSON key-value store.

[npm-image]: https://img.shields.io/npm/v/@varasto/storage.svg
[npm-url]: https://npmjs.org/package/@varasto/storage

- [Installation](#installation)
- [Usage](#usage)
  - [Storing items](#storing-items)
  - [Retrieving items](#retrieving-items)
  - [Removing items](#removing-items)
  - [Searching for entries](#searching-for-entries)
  - [Updating already existing item](#updating-already-existing-item)
  - [Testing whether an item exists or not](#testing-whether-an-item-exists-or-not)
  - [Listing keys stored in a namespace](#listing-keys-stored-in-a-namespace)
  - [Listing values stored in a namespace](#listing-values-stored-in-a-namespace)
  - [Listing entries stored in a namespace](#listing-entries-stored-in-a-namespace)
  - [Filtering entries stored in a namespace](#filtering-entries-stored-in-a-namespace)
  - [Map operation](#map-operation)

## Installation

```shell
$ npm install --save @varasto/storage
```

## Usage

This package provides abstract base class for Varasto storage implementations
as well as error classes to indicate that an item identifier (either namespace
or key) does not pass the slug validation or that an item being updated does
not exist.

Usually you don't need to use or install this package directly, but use an
storage implementation package instead. Below is an list of storage
implementations for different use cases.

| Name                   | Description                               |
| ---------------------- | ----------------------------------------- |
| [cache-storage]        | Acts as an cache for another storage.     |
| [event-target-storage] | Middleware that dispatches events.        |
| [fs-storage]           | Stores data persistently to hard disk.    |
| [memory-storage]       | Stores data to memory.                    |
| [multi-storage]        | Stores data to multiple other storages.   |
| [postgres-storage]     | Stores data to [PostgreSQL] database.     |
| [remote-storage]       | Stores data to remote server.             |
| [redis-storage]        | Stores data to [Redis].                   |
| [single-file-storage]  | Stores data to a single file.             |
| [sqlite-storage]       | Stores data to [SQLite] database.         |
| [validator-storage]    | Acts as an validator for another storage. |
| [web-storage]          | Stores data to browser storage.           |

[cache-storage]: https://www.npmjs.com/package/@varasto/cache-storage
[event-target-storage]: https://www.npmjs.com/package/@varasto/event-target-storage
[fs-storage]: https://www.npmjs.com/package/@varasto/fs-storage
[memory-storage]: https://www.npmjs.com/package/@varasto/memory-storage
[multi-storage]: https://www.npmjs.com/package/@varasto/multi-storage
[postgres-storage]: https://www.npmjs.com/package/@varasto/postgres-storage
[remote-storage]: https://www.npmjs.com/package/@varasto/remote-storage
[redis-storage]: https://www.npmjs.com/package/@varasto/redis-storage
[single-file-storage]: https://www.npmjs.com/package/@varasto/single-file-storage
[sqlite-storage]: https://www.npmjs.com/package/@varasto/sqlite-storage
[validator-storage]: https://www.npmjs.com/package/@varasto/validator-storage
[web-storage]: https://www.npmjs.com/package/@varasto/web-storage
[postgresql]: https://www.postgresql.org
[redis]: https://redis.io
[sqlite]: https://www.sqlite.org/

### Storing items

```TypeScript
set<T extends JsonObject>(
  namespace: string,
  key: string,
  value: T
): Promise<void>
```

Attempts to store an item identified by `namespace` and `key`. Returned
promise will fail if an I/O error occurs while storing the item.

### Retrieving items

```TypeScript
get<T extends JsonObject>(
  namespace: string,
  key: string
): Promise<T | undefined>
```

Attempts to retrieve an item identified by `namespace` and `key`. Returned
promise will either resolve into the value, or `undefined` if item with the
given identifier does not exist. The promise will fail if an I/O error
occurs while retrieving the item.

### Removing items

```TypeScript
delete(
  namespace: string,
  key: string
): Promise<boolean>
```

Attempts to remove an item identified by `namespace` and `key`. Returned
promise will resolve into a boolean value which tells whether an value with
the given identifier existed or not. The promise will fail if an I/O error
occurs while removing the item.

### Searching for entries

```TypeScript
find<T extends JsonObject>(
  namespace: string,
  callback: (value: T, key: string) => boolean
): Promise<[string, T | undefined]>
```

Returns the first entry from specified namespace to which given callback
function returns `true` for, or `undefined` if the callback function does not
return `true` for any entry in the namespace.

The promise will fail if an I/O error occurs, or if given namespace is not a
valid slug.

### Updating already existing item

```TypeScript
update<T extends JsonObject>(
  namespace: string,
  key: string,
  value: Partial<T>
): Promise<T>
```

Attempts to update an already existing item identified by `namespace` and `key`
by shallowly merging with the given new data. Returned promise will resolve
into the new value, or will fail if no such item exists.

### Testing whether an item exists or not

```TypeScript
has(
  namespace: string,
  key: string
): Promise<boolean>
```

Returns `true` if an item identified by `namespace` and `key` exists in the
storage, or `false` if it doesn't. The promise will fail if an I/O error
occurs while testing whether item exists or not.

### Listing keys stored in a namespace

```TypeScript
keys(
  namespace: string
): AsyncGenerator<string>
```

Lists keys of all items stored under an namespace. The promise will fail if an
I/O error occurs while listing the keys.

### Listing values stored in a namespace

```TypeScript
values<T extends JsonObject>(
  namespace: string
): AsyncGenerator<T>
```

Lists all items stored under an namespace. The promise will fail if an I/O
error occurs.

### Listing entries stored in a namespace

```TypeScript
entries<T extends JsonObject>(
  namespace: string
): AsyncGenerator<[string, T]>
```

Lists all items stored under an namespace, with the keys they are identified
by. The promise will fail if an I/O error occurs.

### Filtering entries stored in a namespace

```TypeScript
filter<T extends JsonObject>(
  namespace: string,
  callback: (value: T, key: string) => boolean
): AsyncGenerator<[string, T]>
```

Goes through all entries from the given namespace, returning ones for which
the given callback functions returns `true` for.

The promise will fail if an I/O error occurs, or if given namespace is not a
valid slug.

### Map operation

```TypeScript
map<T extends JsonObject, U extends JsonObject>(
  namespace: string,
  callback: (value: T, key: string) => U
): AsyncGenerator<[string, U]>
```

Goes through all entries from the given namespace, passing them to the given
callback function and returning whatever the callback function returned.

The promise will fail if an I/O error occurs, or if given namespace is not a
valid slug.

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