1. Home
  2. Reference documentation
  3. Compute
  4. Language SDKs
  5. JavaScript
  6. @fastly/js-compute
  7. kv-store

KVStore

Classin kv-store@fastly/js-compute 4.0.0View source

Class for accessing a Fastly KV store.

A KV store is a persistent, globally consistent key-value store. See Data stores for Fastly services for initialization and usage details.

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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

View source
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

View source
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

View source
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

View source
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

View source
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.
Fastly
© Fastly 2026