Class KVStore

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.

Example

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.

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

    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

  • 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.

    Version

    3.13.0

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 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<null | KVStoreEntry>

    Throws

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

list

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

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

    Parameters

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

      Options for filtering and paginating the key list.

      • Optionalcursor?: string

        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. May be faster but possibly out of date.

      • Optionalprefix?: string

        String prefix for keys to list.

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

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

    Version

    3.26.0

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

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

        Generation counter for conditional writes. The write only succeeds if the current generation of the entry matches this value. Must be a positive integer.

        Version

        3.31.0

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

        Binary metadata to associate with the entry, up to 1000 bytes.

        If passing a string, UTF-8 encoding is used.

        Version

        3.26.0

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

        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.

        Version

        3.26.0

      • Optionalttl?: number

        TTL (time-to-live) for the entry, in seconds.

        Version

        3.26.0

    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.

Settings

Member Visibility

On This Page

Constructors
Methods