# kv-storage

**Repository Path**: mirrors_developit/kv-storage

## Basic Information

- **Project Name**: kv-storage
- **Description**: A proposal for an async key/value storage API for the web
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-08-08
- **Last Updated**: 2026-07-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KV Storage

This document is an explainer for a potential future web platform feature, "KV storage" (short for "key/value storage"). It's similar to [`localStorage`](https://html.spec.whatwg.org/multipage/webstorage.html#webstorage) in utility, but much more modern, and layered on top of IndexedDB.

_This feature was formerly known as "async local storage", but in [#38](https://github.com/domenic/kv-storage/issues/38), folks pointed out that since we don't intend to access the `localStorage` database itself, that name was misleading._

This feature would be implemented as a [built-in module](https://github.com/tc39/proposal-javascript-standard-library/). It would also use IndexedDB as its backing store; see more on that below.

A [full specification](https://domenic.github.io/kv-storage/) is also available.

## Sample code

```js
import { storage } from "std:kv-storage"; // specifier prefix not final

(async () => {
  await storage.set("mycat", "Tom");
  console.assert(await storage.get("mycat") === "Tom");

  console.log(await storage.entries());
  // Logs [["mycat", "Tom"]]

  await storage.delete("mycat");
  console.assert(await storage.get("mycat") === undefined);
})();
```

## Motivation

Local storage is a well-known and well-loved API. It only has one problem: it's synchronous. This leads to [terrible performance](https://hacks.mozilla.org/2012/03/there-is-no-simple-solution-for-local-storage/) and cross-window synchronization issues.

The alternative is IndexedDB. IndexedDB is, however, quite hard to use. It has no simple key/value layer, instead requiring understanding concepts like database upgrades and transactions. Its API is also quite dated; it does not use promises, but instead `IDBRequest` objects with their `onsuccess` and `onerror` methods.

In the face of this, a cottage industry of solutions for "async key/value storage" have sprung up to wrap IndexedDB. Perhaps the most well-known of these is [localForage](https://localforage.github.io/localForage/), which copies the `localStorage` API directly.

After many years of convergence in library-space on this sort of solution, it's time to bring a simple async key/value storage solution out of the cold and into the web platform.

## API

### `Map`-like key/value pair API

Note that keys and values would be allowed to be any [structured-serializable type](https://html.spec.whatwg.org/multipage/structured-data.html#serializable-objects) (see [#2](https://github.com/domenic/kv-storage/issues/2) for more discussion).

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

Sets the value of the entry identified by `key` to `value`. Returns a promise that fulfills with `undefined` once this is complete.

_Note: setting an entry to have the value `undefined` is equivalent to deleting it. See discussion in [#3](https://github.com/domenic/kv-storage/issues/3)._

#### `get(key)`

Returns a promise for the value of the entry identified by `key`, or `undefined` if no value is present.

#### `delete(key)`

Removes the entry identified by `key`, if it exists. Once this completes, returns a promise for undefined.

_Note: this is equivalent to `set(key, undefined)`. See discussion in [#3](https://github.com/domenic/kv-storage/issues/3)._

#### `clear()`

Clears all entries. Returns a promise for `undefined`.

#### `keys()`

Returns a promise for an array containing all the stored keys.

#### `values()`

Returns a promise for an array containing all the stored values.

#### `entries()`

Returns a promise for an array containing all the stored key/value pairs, each as a two-element array.

### `new StorageArea()`: separate storage areas

We additionally expose a `StorageArea` constructor, which allows you to create an "isolated" storage area that is less likely to collide than using the default one:

```js
import { storage, StorageArea } from "std:kv-storage";

(async () => {
  await storage.set("mycat", "Tom");
  console.assert(await storage.get("mycat") === "Tom");

  const otherStorage = new StorageArea("unique string");
  console.assert((await otherStorage.keys()).length === 0);
  await otherStorage.set("mycat", "Jerry");
  console.assert(await otherStorage.get("mycat") === "Jerry");
})();
```

This sort of API has [precedent in localForage](https://www.npmjs.com/package/localforage#multiple-instances), which is notable since localForage otherwise sticks rather strictly to the `localStorage` API surface.

The scope of the default storage area would be per-realm. (Or more precisely, per module map, since it would be created whenever you imported the module.)

### `backingStore`: falling back to IndexedDB

One of the great things about layering KV storage on top of IndexedDB is that, if the developer's code grows beyond the capabilities of a simple key/value store, they can easily transition to the full power of IndexedDB (such as using transactions, indices, or cursors), while reusing their database.

To facilitate this, we include an API that allows you to get a `{ database, store, version }` object identifying the IndexedDB database and store within that database where a given `StorageArea`'s data is being stored:

```js
import { storage } from "std:kv-storage";
import { open as idbOpen } from "https://www.npmjs.com/package/idb/pretend-this-was-a-native-JS-module";

(async () => {
  await storage.set("mycat", "Tom");
  await storage.set("mydog", "Joey");

  const { database, store, version } = storage.backingStore;
  const db = await idbOpen(database, version);
  const tx = db.transaction(store, "readwrite");
  tx.objectStore(store).add("mycat", "Jerry");
  tx.objectStore(store).add("mydog", "Kelby");
  await tx.complete;
  await db.close();
})();
```

### Open issues and questions

Please see [the issue tracker](https://github.com/domenic/kv-storage/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Aapi) for open issues on the API surface detailed above.

## Impact

This feature would be low-effort, medium-reward.

- Developers would be steered away from the perils of `localStorage`, toward this modern, attractive alternative.
- Applications would no longer need to ship complex IndexedDB logic, or the 9.5 KB localForage library.

localForage is downloaded [~134K times per week](https://www.npmjs.com/package/localforage) via npm.

Another notable library in this vein is [idb-keyval](https://www.npmjs.com/package/idb-keyval), which is downloaded ~11K times per week via npm.

For comparison, Angular is downloaded [~313K times per week](https://www.npmjs.com/package/angular), React [~2.807 million times per week](https://www.npmjs.com/package/react), and Vue [~436K times per week](https://www.npmjs.com/package/vue).

(All of the above statistics are as of 2018-10-10.)