Cloud

Add to the operation a check that ensures that the versionstamp of the key-value pair in the KV store matches the given versionstamp. If the check fails, the entire operation will fail and no mutations will be performed during the commit.

Commit the operation to the KV store. Returns a value indicating whether checks passed and mutations were performed. If the operation failed because of a failed check, the return value will be a Deno.KvCommitError with an ok: false property. If the operation failed for any other reason (storage error, invalid value, etc.), an exception will be thrown. If the operation succeeded, the return value will be a Deno.KvCommitResult object with a ok: true property and the versionstamp of the value committed to KV.

If the commit returns ok: false, one may create a new atomic operation with updated checks and mutations and attempt to commit it again. See the note on optimistic locking in the documentation for Deno.AtomicOperation.

Add to the operation a mutation that deletes the specified key if all checks pass during the commit.

Add to the operation a mutation that enqueues a value into the queue if all checks pass during the commit.

Shortcut for creating a max mutation. This method wraps n in a Deno.KvU64, so the value of n must be in the range [0, 2^64-1].

Shortcut for creating a min mutation. This method wraps n in a Deno.KvU64, so the value of n must be in the range [0, 2^64-1].

Add to the operation a mutation that performs the specified mutation on the specified key if all checks pass during the commit. The types and semantics of all available mutations are described in the documentation for Deno.KvMutation.

Add to the operation a mutation that sets the value of the specified key to the specified value if all checks pass during the commit.

Optionally an expireIn option can be specified to set a time-to-live (TTL) for the key. The TTL is specified in milliseconds, and the key will be deleted from the database at earliest after the specified number of milliseconds have elapsed. Once the specified duration has passed, the key may still be visible for some additional time. If the expireIn option is not specified, the key will not expire.

Shortcut for creating a sum mutation. This method wraps n in a Deno.KvU64, so the value of n must be in the range [0, 2^64-1].

Create a new Deno.AtomicOperation object which can be used to perform an atomic transaction on the database. This does not perform any operations on the database - the atomic transaction must be committed explicitly using the Deno.AtomicOperation.commit method once all checks and mutations have been added to the operation.

Close the database connection. This will prevent any further operations from being performed on the database, and interrupt any in-flight operations immediately.

Get a symbol that represents the versionstamp of the current atomic operation. This symbol can be used as the last part of a key in .set(), both directly on the Kv object and on an AtomicOperation object created from this Kv instance.

Delete the value for the given key from the database. If no value exists for the key, this operation is a no-op.

const db = await Deno.openKv();
await db.delete(["foo"]);

Add a value into the database queue to be delivered to the queue listener via Deno.Kv.listenQueue.

const db = await Deno.openKv();
await db.enqueue("bar");

The delay option can be used to specify the delay (in milliseconds) of the value delivery. The default delay is 0, which means immediate delivery.

const db = await Deno.openKv();
await db.enqueue("bar", { delay: 60000 });

The keysIfUndelivered option can be used to specify the keys to be set if the value is not successfully delivered to the queue listener after several attempts. The values are set to the value of the queued message.

The backoffSchedule option can be used to specify the retry policy for failed message delivery. Each element in the array represents the number of milliseconds to wait before retrying the delivery. For example, [1000, 5000, 10000] means that a failed delivery will be retried at most 3 times, with 1 second, 5 seconds, and 10 seconds delay between each retry.

const db = await Deno.openKv();
await db.enqueue("bar", {
  keysIfUndelivered: [["foo", "bar"]],
  backoffSchedule: [1000, 5000, 10000],
});

Retrieve the value and versionstamp for the given key from the database in the form of a Deno.KvEntryMaybe. If no value exists for the key, the returned entry will have a null value and versionstamp.

const db = await Deno.openKv();
const result = await db.get(["foo"]);
result.key; // ["foo"]
result.value; // "bar"
result.versionstamp; // "00000000000000010000"

The consistency option can be used to specify the consistency level for the read operation. The default consistency level is "strong". Some use cases can benefit from using a weaker consistency level. For more information on consistency levels, see the documentation for Deno.KvConsistencyLevel.

Retrieve multiple values and versionstamps from the database in the form of an array of Deno.KvEntryMaybe objects. The returned array will have the same length as the keys array, and the entries will be in the same order as the keys. If no value exists for a given key, the returned entry will have a null value and versionstamp.

const db = await Deno.openKv();
const result = await db.getMany([["foo"], ["baz"]]);
result[0].key; // ["foo"]
result[0].value; // "bar"
result[0].versionstamp; // "00000000000000010000"
result[1].key; // ["baz"]
result[1].value; // null
result[1].versionstamp; // null

The consistency option can be used to specify the consistency level for the read operation. The default consistency level is "strong". Some use cases can benefit from using a weaker consistency level. For more information on consistency levels, see the documentation for Deno.KvConsistencyLevel.

Retrieve a list of keys in the database. The returned list is an Deno.KvListIterator which can be used to iterate over the entries in the database.

Each list operation must specify a selector which is used to specify the range of keys to return. The selector can either be a prefix selector, or a range selector:

• A prefix selector selects all keys that start with the given prefix of key parts. For example, the selector ["users"] will select all keys that start with the prefix ["users"], such as ["users", "alice"] and ["users", "bob"]. Note that you can not partially match a key part, so the selector ["users", "a"] will not match the key ["users", "alice"]. A prefix selector may specify a start key that is used to skip over keys that are lexicographically less than the start key.
• A range selector selects all keys that are lexicographically between the given start and end keys (including the start, and excluding the end). For example, the selector ["users", "a"], ["users", "n"] will select all keys that start with the prefix ["users"] and have a second key part that is lexicographically between a and n, such as ["users", "alice"], ["users", "bob"], and ["users", "mike"], but not ["users", "noa"] or ["users", "zoe"].

const db = await Deno.openKv();
const entries = db.list({ prefix: ["users"] });
for await (const entry of entries) {
  entry.key; // ["users", "alice"]
  entry.value; // { name: "Alice" }
  entry.versionstamp; // "00000000000000010000"
}

The options argument can be used to specify additional options for the list operation. See the documentation for Deno.KvListOptions for more information.

Listen for queue values to be delivered from the database queue, which were enqueued with Deno.Kv.enqueue. The provided handler callback is invoked on every dequeued value. A failed callback invocation is automatically retried multiple times until it succeeds or until the maximum number of retries is reached.

const db = await Deno.openKv();
db.listenQueue(async (msg: unknown) => {
  await db.set(["foo"], msg);
});

Set the value for the given key in the database. If a value already exists for the key, it will be overwritten.

const db = await Deno.openKv();
await db.set(["foo"], "bar");

Optionally an expireIn option can be specified to set a time-to-live (TTL) for the key. The TTL is specified in milliseconds, and the key will be deleted from the database at earliest after the specified number of milliseconds have elapsed. Once the specified duration has passed, the key may still be visible for some additional time. If the expireIn option is not specified, the key will not expire.

Watch for changes to the given keys in the database. The returned stream is a ReadableStream that emits a new value whenever any of the watched keys change their versionstamp. The emitted value is an array of Deno.KvEntryMaybe objects, with the same length and order as the keys array. If no value exists for a given key, the returned entry will have a null value and versionstamp.

The returned stream does not return every single intermediate state of the watched keys, but rather only keeps you up to date with the latest state of the keys. This means that if a key is modified multiple times quickly, you may not receive a notification for every single change, but rather only the latest state of the key.

const db = await Deno.openKv();

const stream = db.watch([["foo"], ["bar"]]);
for await (const entries of stream) {
  entries[0].key; // ["foo"]
  entries[0].value; // "bar"
  entries[0].versionstamp; // "00000000000000010000"
  entries[1].key; // ["bar"]
  entries[1].value; // null
  entries[1].versionstamp; // null
}

The options argument can be used to specify additional options for the watch operation. The raw option can be used to specify whether a new value should be emitted whenever a mutation occurs on any of the watched keys (even if the value of the key does not change, such as deleting a deleted key), or only when entries have observably changed in some way. When raw: true is used, it is possible for the stream to occasionally emit values even if no mutations have occurred on any of the watched keys. The default value for this option is false.

Returns the cursor of the current position in the iteration. This cursor can be used to resume the iteration from the current position in the future by passing it to the cursor option of the list method.

Create a new KvU64 instance from the given bigint value. If the value is signed or greater than 64-bits, an error will be thrown.

The value of this unsigned 64-bit integer, represented as a bigint.

The versionstamp of the value committed to KV.

The maximum number of key-value pairs to return. If not specified, all matching key-value pairs will be returned.

The cursor to resume the iteration from. If not specified, the iteration will start from the beginning.

Whether to reverse the order of the returned key-value pairs. If not specified, the order will be ascending from the start of the range as per the lexicographical ordering of the keys. If true, the order will be descending from the end of the range.

The default value is false.

The consistency level of the list operation. The default consistency level is "strong". Some use cases can benefit from using a weaker consistency level. For more information on consistency levels, see the documentation for Deno.KvConsistencyLevel.

List operations are performed in batches (in sizes specified by the batchSize option). The consistency level of the list operation is applied to each batch individually. This means that while each batch is guaranteed to be consistent within itself, the entire list operation may not be consistent across batches because a mutation may be applied to a key-value pair between batches, in a batch that has already been returned by the list operation.

The size of the batches in which the list operation is performed. Larger or smaller batch sizes may positively or negatively affect the performance of a list operation depending on the specific use case and iteration behavior. Slow iterating queries may benefit from using a smaller batch size for increased overall consistency, while fast iterating queries may benefit from using a larger batch size for better performance.

The default batch size is equal to the limit option, or 100 if this is unset. The maximum value for this option is 500. Larger values will be clamped.