add ArrayVec-backed serialized query overload; doc comments

Signed-off-by: Jason Volk <jason@zemos.net>

Cargo.lock

@@ -726,6 +726,7 @@ dependencies = [
 name = "conduit_database"
 version = "0.4.7"
 dependencies = [
+ "arrayvec",
  "conduit_core",
  "const-str",
  "futures",

src/database/Cargo.toml

@@ -35,6 +35,7 @@ zstd_compression = [
 ]
 
 [dependencies]
+arrayvec.workspace = true
 conduit-core.workspace = true
 const-str.workspace = true
 futures.workspace = true

src/database/de.rs

@@ -195,7 +195,7 @@ impl<'a, 'de: 'a> de::Deserializer<'de> for &'a mut Deserializer<'de> {
 	}
 
 	fn deserialize_u8<V: Visitor<'de>>(self, _visitor: V) -> Result<V::Value> {
-		unimplemented!("deserialize u8 not implemented")
+		unimplemented!("deserialize u8 not implemented; try dereferencing the Handle for [u8] access instead")
 	}
 
 	fn deserialize_u16<V: Visitor<'de>>(self, _visitor: V) -> Result<V::Value> {

src/database/handle.rs

@@ -35,18 +35,6 @@ impl Serialize for Handle<'_> {
 	}
 }
 
-impl Deref for Handle<'_> {
-	type Target = Slice;
-
-	#[inline]
-	fn deref(&self) -> &Self::Target { &self.val }
-}
-
-impl AsRef<Slice> for Handle<'_> {
-	#[inline]
-	fn as_ref(&self) -> &Slice { &self.val }
-}
-
 impl Deserialized for Result<Handle<'_>> {
 	#[inline]
 	fn map_de<T, U, F>(self, f: F) -> Result<U>
@@ -78,3 +66,19 @@ impl<'a> Deserialized for &'a Handle<'a> {
 		deserialize_val(self.as_ref()).map(f)
 	}
 }
+
+impl From<Handle<'_>> for Vec<u8> {
+	fn from(handle: Handle<'_>) -> Self { handle.deref().to_vec() }
+}
+
+impl Deref for Handle<'_> {
+	type Target = Slice;
+
+	#[inline]
+	fn deref(&self) -> &Self::Target { &self.val }
+}
+
+impl AsRef<Slice> for Handle<'_> {
+	#[inline]
+	fn as_ref(&self) -> &Slice { &self.val }
+}

src/database/map/get.rs

@@ -1,5 +1,6 @@
 use std::{convert::AsRef, fmt::Debug, future::Future, io::Write};
 
+use arrayvec::ArrayVec;
 use conduit::{err, implement, Result};
 use futures::future::ready;
 use serde::Serialize;
@@ -11,6 +12,9 @@ use crate::{
 	Handle,
 };
 
+/// Fetch a value from the database into cache, returning a reference-handle
+/// asynchronously. The key is serialized into an allocated buffer to perform
+/// the query.
 #[implement(super::Map)]
 pub fn qry<K>(&self, key: &K) -> impl Future<Output = Result<Handle<'_>>> + Send
 where
@@ -20,6 +24,20 @@ where
 	self.bqry(key, &mut buf)
 }
 
+/// Fetch a value from the database into cache, returning a reference-handle
+/// asynchronously. The key is serialized into a fixed-sized buffer to perform
+/// the query. The maximum size is supplied as const generic parameter.
+#[implement(super::Map)]
+pub fn aqry<const MAX: usize, K>(&self, key: &K) -> impl Future<Output = Result<Handle<'_>>> + Send
+where
+	K: Serialize + ?Sized + Debug,
+{
+	let mut buf = ArrayVec::<u8, MAX>::new();
+	self.bqry(key, &mut buf)
+}
+
+/// Fetch a value from the database into cache, returning a reference-handle
+/// asynchronously. The key is serialized into a user-supplied Writer.
 #[implement(super::Map)]
 #[tracing::instrument(skip(self, buf), fields(%self), level = "trace")]
 pub fn bqry<K, B>(&self, key: &K, buf: &mut B) -> impl Future<Output = Result<Handle<'_>>> + Send
@@ -31,6 +49,8 @@ where
 	self.get(key)
 }
 
+/// Fetch a value from the database into cache, returning a reference-handle
+/// asynchronously. The key is referenced directly to perform the query.
 #[implement(super::Map)]
 pub fn get<K>(&self, key: &K) -> impl Future<Output = Result<Handle<'_>>> + Send
 where
@@ -39,6 +59,9 @@ where
 	ready(self.get_blocking(key))
 }
 
+/// Fetch a value from the database into cache, returning a reference-handle.
+/// The key is referenced directly to perform the query. This is a thread-
+/// blocking call.
 #[implement(super::Map)]
 #[tracing::instrument(skip(self, key), fields(%self), level = "trace")]
 pub fn get_blocking<K>(&self, key: &K) -> Result<Handle<'_>>

src/database/map/remove.rs

@@ -1,5 +1,6 @@
 use std::{convert::AsRef, fmt::Debug, io::Write};
 
+use arrayvec::ArrayVec;
 use conduit::implement;
 use serde::Serialize;
 
@@ -14,6 +15,15 @@ where
 	self.bdel(key, &mut buf);
 }
 
+#[implement(super::Map)]
+pub fn adel<const MAX: usize, K>(&self, key: &K)
+where
+	K: Serialize + ?Sized + Debug,
+{
+	let mut buf = ArrayVec::<u8, MAX>::new();
+	self.bdel(key, &mut buf);
+}
+
 #[implement(super::Map)]
 #[tracing::instrument(skip(self, buf), fields(%self), level = "trace")]
 pub fn bdel<K, B>(&self, key: &K, buf: &mut B)