Skip to main content
Module

x/kv_toolbox/batched_atomic.ts>BatchedAtomicOperation

Utilities for working with Deno KV 🦕🗝️
Go to Latest
class BatchedAtomicOperation
import { BatchedAtomicOperation } from "https://deno.land/x/kv_toolbox@0.17.0/batched_atomic.ts";

The class that encapsulates the batched atomic operations. Works around limitations imposed by Deno KV related to individual atomic operations.

Constructors

new
BatchedAtomicOperation(kv: Deno.Kv, unnamed 1?: { maxChecks?: number; maxMutations?: number; maxBytes?: number; maxKeyBytes?: number; })

Methods

check(...checks: Deno.AtomicCheck[]): this

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.

If there are additional batches of atomic operations to perform, they will be abandoned.

checkBlob(...checks: Deno.AtomicCheck[]): this

Add to the operation a check that ensures that the versionstamp of the blob 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.

The blob should have previously been set via kv-toolbox's set() or as part of an batched atomic operation via setBlob().

If there are additional batches of atomic operations to perform, they will be abandoned.

Commit the operation to the KV store. Returns an array of values indicating whether checks passed and mutations were performed. If the operation failed because of a failed check, the last element of 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.), the promise will be rejected with an exception. If the operation succeeded, the return value will be an individual Deno.KvCommitResult object with a ok: true property and the versionstamp of the value committed to KV broken up by the batch size, which defaults to 10.

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.

delete(key: Deno.KvKey): this

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

Add to the operation a set of mutations to delete the specified parts of a blob value if all checks pass during the commit.

enqueue(value: unknown, options?: { delay?: number; keysIfUndelivered?: Deno.KvKey[]; backoffSchedule?: number[]; }): this

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

max(key: Deno.KvKey, n: bigint): this

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

min(key: Deno.KvKey, n: bigint): this

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

mutate(...mutations: Deno.KvMutation[]): this

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.

set(
value: unknown,
options?: { expireIn?: number; },
): this

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.

setBlob(
value: ArrayBufferLike | ReadableStream<Uint8Array> | Blob,
options?: { expireIn?: number; },
): this

Add to the operation a mutation that sets a blob value in the store if all checks pass during the commit. The blob can be any array buffer like structure, a byte ReadableStream, or a Blob or File.

sum(key: Deno.KvKey, n: bigint): this

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