// A generic keyvalue interface for WASI.
interface types {
/// 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,
/// 1. Amazon DynamoDB calls a collection of key-value pairs a table
/// 2. Redis has hashes, sets, and sorted sets as different types of collections
/// 3. Cassandra calls a collection of key-value pairs a column family
/// 4. MongoDB calls a collection of key-value pairs a collection
/// 5. Riak calls a collection of key-value pairs a bucket
/// 6. Memcached calls a collection of key-value pairs a slab
/// 7. 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
// Soon: switch to `resource bucket { ... }`
resource bucket {
/// Opens a bucket with the given name.
///
/// If any error occurs, including if the bucket does not exist, it returns an `Err(error)`.
open-bucket: static func(name: string) -> result<bucket, error>;
}
/// A key is a unique identifier for a value in a bucket. The key is used to
/// retrieve the value from the bucket.
type key = string;
use wasi-keyvalue-error.{ error };
/// A value is the data stored in a key-value pair. The value can be of any type
/// that can be represented in a byte array.
// Soon: switch to `resource value { ... }`
resource outgoing-value {
new-outgoing-value: static func() -> outgoing-value;
/// Writes the value asynchronously by consuming the given `stream<u8>`:
/// the caller keeps the writable end and the host appends every received
/// byte to the outgoing value's body.
/// If any other error occurs, it returns an `Err(error)`.
outgoing-value-write-body-async: func(data: stream<u8>) -> result<_, error>;
/// Writes the value synchronously.
/// If any other error occurs, it returns an `Err(error)`.
outgoing-value-write-body-sync: func(value: list<u8>) -> result<_, error>;
}
/// A incoming-value is a wrapper around a value. It provides ways to read the value.
///
/// The incoming-value provides two ways to consume the value:
/// 1. `incoming-value-consume-sync` consumes the value synchronously and returns the
/// value as a `list<u8>`.
/// 2. `incoming-value-consume-async` consumes the value asynchronously and returns the
/// value as a `stream<u8>`.
/// In addition, it provides a `incoming-value-size` function to get the size of the value.
/// This is useful when the value is large and the caller wants to allocate a buffer of
/// the right size to consume the value.
// Soon: switch to `resource incoming-value { ... }`
resource incoming-value {
/// Consumes the value synchronously and returns the value as a list of bytes.
/// If any other error occurs, it returns an `Err(error)`.
incoming-value-consume-sync: func() -> result<list<u8>, error>;
/// Consumes the value asynchronously and returns the value as a `stream<u8>`.
/// If any other error occurs, it returns an `Err(error)`.
incoming-value-consume-async: func() -> result<stream<u8>, error>;
/// The size of the value in bytes.
/// If the size is unknown or unavailable, this function returns an `Err(error)`.
incoming-value-size: func() -> result<u64, error>;
}
}