Class KVStore

Class for accessing a Fastly KV-store.

A kv store is a persistent, globally consistent key-value store.

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

Example

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

/// <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)))

Constructors

constructor

Methods

delete get list put

Constructors

constructor

  • new KVStore(name: string): KVStore

    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.

    Returns KVStore

Methods

delete

  • delete(key: string): Promise<undefined>

    Delete the value associated with the key key in the KV Store.

    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<undefined>

get

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

    Gets the value associated with the key key in the KV Store. When the key is present, a resolved Promise containing an 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<null | KVStoreEntry>

list

  • list(
        options?: {
            cursor?: string;
            limit?: number;
            noSync?: boolean;
            prefix?: string;
        },
    ): { cursor: undefined
    | string; list: string[] }

    Returns an async iterator for the values of the KV Store optionally taking a prefix and limit

    Parameters

    • Optionaloptions: { cursor?: string; limit?: number; noSync?: boolean; prefix?: string }
      • Optionalcursor?: string

        Cursor

        The base64 cursor string representing the last listing operation

      • Optionallimit?: number

        Limit the number of keys provided per listing.

      • OptionalnoSync?: boolean

        Do not wait to sync the key list, and instead immediately return the current cached key list.

      • Optionalprefix?: string

        String prefix for keys to list.

    Returns { cursor: undefined | string; list: string[] }

    • cursor: undefined | string

      Pass this base64 cursor into a subsequent list call to obtain the next listing.

      The cursor is undefined when the end of the list is reached.

    • list: string[]

put

  • put(
        key: string,
        value: BodyInit,
        options?: {
            gen?: number;
            metadata?: string | ArrayBuffer | ArrayBufferView<ArrayBufferLike>;
            mode?: "overwrite" | "add" | "append" | "prepend";
            ttl?: 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. 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.

    • Optionaloptions: {
          gen?: number;
          metadata?: string | ArrayBuffer | ArrayBufferView<ArrayBufferLike>;
          mode?: "overwrite" | "add" | "append" | "prepend";
          ttl?: number;
      }
      • Optionalgen?: number

        If generation match integer.

      • Optionalmetadata?: string | ArrayBuffer | ArrayBufferView<ArrayBufferLike>

        Optional metadata to be associated with the entry.

        If passing a string, UTF-8 encoding is used

      • Optionalmode?: "overwrite" | "add" | "append" | "prepend"

        Insert mode, defaults to 'overwrite'.

      • Optionalttl?: number

        TTL for the entry.

    Returns Promise<undefined>

Settings

Member Visibility

On This Page

Constructors
Methods