import { Deno } from "https://deno.land/x/deno@v2.0.4/cli/tsc/dts/lib.deno.unstable.d.ts";
const { AtomicOperation } = Deno;
UNSTABLE: New API, yet to be vetted.
An operation on a Deno.Kv that can be performed
atomically. Atomic operations do not auto-commit, and must be committed
explicitly by calling the commit method.
Atomic operations can be used to perform multiple mutations on the KV store
in a single atomic transaction. They can also be used to perform
conditional mutations by specifying one or more
Deno.AtomicChecks that ensure that a mutation is only performed
if the key-value pair in the KV has a specific versionstamp. If any of the
checks fail, the entire operation will fail and no mutations will be made.
The ordering of mutations is guaranteed to be the same as the ordering of the mutations specified in the operation. Checks are performed before any mutations are performed. The ordering of checks is unobservable.
Atomic operations can be used to implement optimistic locking, where a mutation is only performed if the key-value pair in the KV store has not been modified since the last read. This can be done by specifying a check that ensures that the versionstamp of the key-value pair matches the versionstamp that was read. If the check fails, the mutation will not be performed and the operation will fail. One can then retry the read-modify- write operation in a loop until it succeeds.
The commit method of an atomic operation 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.
Methods
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].