A keyvalue interface that provides atomic operations.
Atomic operations are single, indivisible operations. When a fault causes an atomic operation to fail, it will appear to the invoker of the atomic operation that the action either completed successfully or did nothing at all.
Please note that this interface is bare functions that take a reference to a bucket. This is to
get around the current lack of a way to "extend" a resource with additional methods inside of
wit. Future version of the interface will instead extend these methods on the base bucket
resource.
Types
use resource bucket
from wasi:keyvalue/store@0.2.0-draft
A bucket is a collection of key-value pairs. Each key-value pair is stored as a entry in the bucket, and the bucket itself acts as a collection of all these entries.
It is worth noting that the exact terminology for bucket in key-value stores can very depending on the specific implementation. For example:
- Amazon DynamoDB calls a collection of key-value pairs a table
- Redis has hashes, sets, and sorted sets as different types of collections
- Cassandra calls a collection of key-value pairs a column family
- MongoDB calls a collection of key-value pairs a collection
- Riak calls a collection of key-value pairs a bucket
- Memcached calls a collection of key-value pairs a slab
- Azure Cosmos DB calls a collection of key-value pairs a container
In this interface, we use the term bucket to refer to a collection of key-value pairs
get: func(key: string) -> result<option<list<u8>>, error>Get the value associated with the specified
keyThe value is returned as an option. If the key-value pair exists in the store, it returns
Ok(value). If the key does not exist in the store, it returnsOk(none).If any other error occurs, it returns an
Err(error).set: func(key: string, value: list<u8>) -> result<_, error>Set the value associated with the key in the store. If the key already exists in the store, it overwrites the value.
If the key does not exist in the store, it creates a new key-value pair.
If any other error occurs, it returns an
Err(error).delete: func(key: string) -> result<_, error>Delete the key-value pair associated with the key in the store.
If the key does not exist in the store, it does nothing.
If any other error occurs, it returns an
Err(error).exists: func(key: string) -> result<bool, error>Check if the key exists in the store.
If the key exists in the store, it returns
Ok(true). If the key does not exist in the store, it returnsOk(false).If any other error occurs, it returns an
Err(error).list-keys: func(cursor: option<u64>) -> result<key-response, error>Get all the keys in the store with an optional cursor (for use in pagination). It returns a list of keys. Please note that for most KeyValue implementations, this is a can be a very expensive operation and so it should be used judiciously. Implementations can return any number of keys in a single response, but they should never attempt to send more data than is reasonable (i.e. on a small edge device, this may only be a few KB, while on a large machine this could be several MB). Any response should also return a cursor that can be used to fetch the next page of keys. See the
key-responserecord for more information.Note that the keys are not guaranteed to be returned in any particular order.
If the store is empty, it returns an empty list.
MAY show an out-of-date list of keys if there are concurrent writes to the store.
If any error occurs, it returns an
Err(error).
use variant error
from wasi:keyvalue/store@0.2.0-draft
The set of errors which may be raised by functions in this package
no-such-storeThe host does not recognize the store identifier requested.
access-deniedThe requesting component does not have access to the specified store (which may or may not exist).
other:stringSome implementation-specific error has occurred (e.g. I/O)
Functions
increment: func(
bucket: borrow<bucket>,
key: string,
delta: u64,
) -> result<u64, error>
Atomically increment the value associated with the key in the store by the given delta. It returns the new value.
If the key does not exist in the store, it creates a new key-value pair with the value set to the given delta.
If any other error occurs, it returns an Err(error).
WIT
/// A keyvalue interface that provides atomic operations.
///
/// Atomic operations are single, indivisible operations. When a fault causes an atomic operation to
/// fail, it will appear to the invoker of the atomic operation that the action either completed
/// successfully or did nothing at all.
///
/// Please note that this interface is bare functions that take a reference to a bucket. This is to
/// get around the current lack of a way to "extend" a resource with additional methods inside of
/// wit. Future version of the interface will instead extend these methods on the base `bucket`
/// resource.
interface atomics {
use store.{bucket, error};
/// Atomically increment the value associated with the key in the store by the given delta. It
/// returns the new value.
///
/// If the key does not exist in the store, it creates a new key-value pair with the value set
/// to the given delta.
///
/// If any other error occurs, it returns an `Err(error)`.
increment: func(bucket: borrow<bucket>, key: string, delta: u64) -> result<u64, error>;
}