---
title: KVStore
summary: Class for accessing a Fastly KV store.
url: https://www.fastly.com/documentation/reference/compute/sdks/javascript/js-compute/kv-store/class.KVStore/
---

**Kind:** Class  
**Module:** [kv-store](https://www.fastly.com/documentation/reference/compute/sdks/javascript/js-compute/kv-store/)  
**Package:** @fastly/js-compute 4.0.1  
**Source:** https://github.com/fastly/js-compute-runtime/blob/70cf30af4e657879b2d1e7eafab880e39e3a3f7d/types/kv-store.d.ts#L36

Class for accessing a [Fastly KV store](https://developer.fastly.com/reference/api/kv-store/).

A KV store is a persistent, globally consistent key-value store. See
[Data stores for Fastly services](https://developer.fastly.com/learning/concepts/edge-state/data-stores#kv-stores)
for initialization and usage details.

**Note**: Can only be used when processing requests, not during build-time initialization.

````javascript
In this example we connect to a KV store named `'files'`, save an entry to the store
under the key `'hello'` and then read back the value and return it to the client.

```js
/// <reference types="@fastly/js-compute" />

import { KVStore } from "fastly:kv-store";

async function app(event) {
  const files = new KVStore('files')

  await files.put('hello', 'world')

  const entry = await files.get('hello')

  return new Response(await entry.text())
}

addEventListener("fetch", (event) => event.respondWith(app(event)))

```
````

## Constructor

**Source:** https://github.com/fastly/js-compute-runtime/blob/70cf30af4e657879b2d1e7eafab880e39e3a3f7d/types/kv-store.d.ts#L46

```javascript
new KVStore(name: string)
```

Creates a new JavaScript KVStore object which interacts with the Fastly KV store named `name`.

**Parameters**

- `name`: `string`

  Name of the Fastly KV store to interact with. A name cannot be empty, contain
    control characters, or be longer than 255 characters.

**Throws**

- `TypeError` if no KV store exists with the provided name, or the name is empty,
  longer than 255 characters, does not start with an ASCII alphabetical character,
  or contains control characters (`\u0000-\u001F`).

## Methods

### delete

**Source:** https://github.com/fastly/js-compute-runtime/blob/70cf30af4e657879b2d1e7eafab880e39e3a3f7d/types/kv-store.d.ts#L58

```javascript
delete(key: string): Promise<undefined>
```

Delete the value associated with the key `key` in the KV store.

**Parameters**

- `key`: `string`

  The key to delete from within the KV store. A key cannot:
  - Be any of the strings "", ".", or ".."
  - Start with the string ".well-known/acme-challenge/"
  - Contain any of the characters "#;?^|\n\r"
  - Be longer than 1024 characters

**Returns**

`Promise<undefined>`

**Throws**

- `TypeError` if the key violates any of the above constraints.

### get

**Source:** https://github.com/fastly/js-compute-runtime/blob/70cf30af4e657879b2d1e7eafab880e39e3a3f7d/types/kv-store.d.ts#L74

```javascript
get(key: string): Promise<KVStoreEntry | null>
```

Gets the value associated with the key `key` in the KV store.

When the key is present, a resolved `Promise` containing a `KVStoreEntry` will be returned
which contains the associated value. When the key is absent, a resolved `Promise`
containing `null` is returned.

**Parameters**

- `key`: `string`

  The key to retrieve from within the KV store. A key cannot:
  - Be any of the strings "", ".", or ".."
  - Start with the string ".well-known/acme-challenge/"
  - Contain any of the characters "#;?^|\n\r"
  - Be longer than 1024 characters

**Returns**

`Promise<KVStoreEntry | null>`

**Throws**

- Throws `TypeError` if the key violates any of the above constraints.

### list

**Source:** https://github.com/fastly/js-compute-runtime/blob/70cf30af4e657879b2d1e7eafab880e39e3a3f7d/types/kv-store.d.ts#L137

```javascript
list(options?: { noSync?: boolean; prefix?: string; limit?: number; cursor?: string }): Promise<{ list: string[]; cursor: string | undefined }>
```

List keys in the KV store, optionally filtered by prefix.

**Parameters**

- `options`: `{ noSync?: boolean; prefix?: string; limit?: number; cursor?: string }` (optional)

  Options for filtering and paginating the key list.

  - `noSync` _optional_: `boolean` — Do not wait to sync the key list, and instead immediately return the current
    cached key list. May be faster but possibly out of date.
  - `prefix` _optional_: `string` — String prefix for keys to list.
  - `limit` _optional_: `number` — Limit the number of keys provided per listing.
  - `cursor` _optional_: `string` — The base64 cursor string representing the last listing operation.

**Returns**

`Promise<{ list: string[]; cursor: string | undefined }>`

A `Promise` resolving with the list of keys and a cursor for pagination.

### put

**Source:** https://github.com/fastly/js-compute-runtime/blob/70cf30af4e657879b2d1e7eafab880e39e3a3f7d/types/kv-store.d.ts#L92

```javascript
put(key: string, value: BodyInit, options?: { metadata?: ArrayBufferView | ArrayBuffer | string; ttl?: number; mode?: 'overwrite' | 'add' | 'append' | 'prepend'; gen?: number }): Promise<undefined>
```

Write the value of `value` into the KV store under the key `key`.

Note: KV store is eventually consistent, this means that the updated contents associated
with the key `key` may not be available to read from all edge locations immediately and
some edge locations may continue returning the previous contents associated with the key.

**Parameters**

- `key`: `string`

  The key to associate with the value in the KV store. A key cannot:
  - Be any of the strings "", ".", or ".."
  - Start with the string ".well-known/acme-challenge/"
  - Contain any of the characters "#;?^|\n\r"
  - Be longer than 1024 characters
- `value`: `BodyInit` — The value to store within the KV store. Maximum size is 30 MB.
- `options`: `{ metadata?: ArrayBufferView | ArrayBuffer | string; ttl?: number; mode?: 'overwrite' | 'add' | 'append' | 'prepend'; gen?: number }` (optional)

  - `metadata` _optional_: `ArrayBufferView | ArrayBuffer | string` _(since 3.26.0)_ — Binary metadata to associate with the entry, up to 1000 bytes.

    If passing a string, UTF-8 encoding is used.
  - `ttl` _optional_: `number` _(since 3.26.0)_ — TTL (time-to-live) for the entry, in seconds.
  - `mode` _optional_: `'overwrite' | 'add' | 'append' | 'prepend'` _(since 3.26.0)_ — Insert mode, defaults to `'overwrite'`.
    - `'overwrite'`: Replace any existing value for the key.
    - `'add'`: Only insert if the key does not already exist.
    - `'append'`: Append to any existing value for the key.
    - `'prepend'`: Prepend to any existing value for the key.
  - `gen` _optional_: `number` _(since 3.31.0)_ — Generation counter for conditional writes. The write only succeeds if the
    current generation of the entry matches this value. Must be a positive integer.

**Returns**

`Promise<undefined>`

**Throws**

- `TypeError` if the key violates any of the above constraints or 
if `gen` is provided and is not a positive integer.