x

crates/pile-value/src/extract/traits.rs

@@ -0,0 +1,68 @@
+/// An attachment that extracts metadata from an [Item].
+///
+/// Metadata is exposed as an immutable map of {label: value},
+/// much like a json object.
+#[async_trait::async_trait]
+pub trait ObjectExtractor: Send + Sync {
+	/// Get the field at `name` from `item`.
+	/// - returns `None` if `name` is not a valid field
+	/// - returns `Some(Null)` if `name` is not available
+	async fn field(
+		&self,
+		name: &pile_config::Label,
+	) -> Result<Option<crate::value::PileValue>, std::io::Error>;
+
+	/// Return all fields in this extractor.
+	/// `Self::field` must return [Some] for all these keys
+	/// and [None] for all others.
+	async fn fields(&self) -> Result<Vec<pile_config::Label>, std::io::Error>;
+
+	/// Convert this to a JSON value.
+	async fn to_json(&self) -> Result<serde_json::Value, std::io::Error> {
+		let keys = self.fields().await?;
+		let mut map = serde_json::Map::new();
+		for k in &keys {
+			let v = match self.field(k).await? {
+				Some(x) => x,
+				None => continue,
+			};
+			map.insert(k.to_string(), Box::pin(v.to_json()).await?);
+		}
+
+		Ok(serde_json::Value::Object(map))
+	}
+}
+
+/// An attachment that extracts metadata from an [Item].
+///
+/// Metadata is exposed as an immutable list of values.
+#[async_trait::async_trait]
+pub trait ListExtractor: Send + Sync {
+	/// Get the item at index `idx`.
+	/// Indices start at zero, and must be consecutive.
+	/// - returns `None` if `idx` is out of range
+	/// - returns `Some(Null)` if `None` is at `idx`
+	async fn get(&self, idx: usize) -> Result<Option<crate::value::PileValue>, std::io::Error>;
+
+	async fn len(&self) -> Result<usize, std::io::Error>;
+
+	async fn is_empty(&self) -> Result<bool, std::io::Error> {
+		Ok(self.len().await? == 0)
+	}
+
+	/// Convert this list to a JSON value.
+	async fn to_json(&self) -> Result<serde_json::Value, std::io::Error> {
+		let len = self.len().await?;
+		let mut list = Vec::with_capacity(len);
+		for i in 0..len {
+			#[expect(clippy::expect_used)]
+			let v = self
+				.get(i)
+				.await?
+				.expect("value must be present according to length");
+			list.push(Box::pin(v.to_json()).await?);
+		}
+
+		Ok(serde_json::Value::Array(list))
+	}
+}