asp/keep
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Add rustdoc to db.rs functions for arguments and returns

Browse Source 
Co-authored-by: aider (openai/andrew/openrouter/deepseek/deepseek-chat-v3.1) <aider@aider.chat>
This commit is contained in:
Andrew Phillips
2025-09-10 11:57:06 -03:00
parent 93d99a644a
commit a72352eb15
1 changed files with 212 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

212
src/db.rs
View File

@@ -185,6 +185,16 @@ pub fn add_meta(conn: &Connection, item_id: i64, name: &str, value: &str) -> Res
store_meta(conn, meta)
}
/// Updates an existing item in the database
///
/// # Arguments
///
/// * `conn` - Database connection
/// * `item` - Item with updated values
///
/// # Returns
///
/// * `Result<()>` - Success or error if the operation fails
pub fn update_item(conn: &Connection, item: Item) -> Result<()> {
debug!("DB: Updating item: {:?}", item);
conn.execute(
@@ -198,12 +208,32 @@ pub fn update_item(conn: &Connection, item: Item) -> Result<()> {
Ok(())
}
/// Deletes an item from the database
///
/// # Arguments
///
/// * `conn` - Database connection
/// * `item` - Item to delete
///
/// # Returns
///
/// * `Result<()>` - Success or error if the operation fails
pub fn delete_item(conn: &Connection, item: Item) -> Result<()> {
debug!("DB: Deleting item: {:?}", item);
conn.execute("DELETE FROM items WHERE id=?1", params![item.id])?;
Ok(())
}
/// Deletes a metadata entry from the database
///
/// # Arguments
///
/// * `conn` - Database connection
/// * `meta` - Metadata entry to delete
///
/// # Returns
///
/// * `Result<()>` - Success or error if the operation fails
pub fn query_delete_meta(conn: &Connection, meta: Meta) -> Result<()> {
debug!("DB: Deleting meta: {:?}", meta);
conn.execute(
@@ -213,6 +243,16 @@ pub fn query_delete_meta(conn: &Connection, meta: Meta) -> Result<()> {
Ok(())
}
/// Inserts or updates a metadata entry in the database
///
/// # Arguments
///
/// * `conn` - Database connection
/// * `meta` - Metadata entry to upsert
///
/// # Returns
///
/// * `Result<()>` - Success or error if the operation fails
pub fn query_upsert_meta(conn: &Connection, meta: Meta) -> Result<()> {
debug!("DB: Inserting meta: {:?}", meta);
conn.execute(
@@ -223,6 +263,16 @@ pub fn query_upsert_meta(conn: &Connection, meta: Meta) -> Result<()> {
Ok(())
}
/// Stores a metadata entry, deleting it if the value is empty
///
/// # Arguments
///
/// * `conn` - Database connection
/// * `meta` - Metadata entry to store
///
/// # Returns
///
/// * `Result<()>` - Success or error if the operation fails
pub fn store_meta(conn: &Connection, meta: Meta) -> Result<()> {
if meta.value.is_empty() {
query_delete_meta(conn, meta)?;
@@ -232,6 +282,16 @@ pub fn store_meta(conn: &Connection, meta: Meta) -> Result<()> {
Ok(())
}
/// Inserts a tag into the database
///
/// # Arguments
///
/// * `conn` - Database connection
/// * `tag` - Tag to insert
///
/// # Returns
///
/// * `Result<()>` - Success or error if the operation fails
pub fn insert_tag(conn: &Connection, tag: Tag) -> Result<()> {
debug!("DB: Inserting tag: {:?}", tag);
conn.execute(
@@ -241,12 +301,33 @@ pub fn insert_tag(conn: &Connection, tag: Tag) -> Result<()> {
Ok(())
}
/// Deletes all tags associated with an item
///
/// # Arguments
///
/// * `conn` - Database connection
/// * `item` - Item whose tags should be deleted
///
/// # Returns
///
/// * `Result<()>` - Success or error if the operation fails
pub fn delete_item_tags(conn: &Connection, item: Item) -> Result<()> {
debug!("DB: Deleting all item tags: {:?}", item);
conn.execute("DELETE FROM tags WHERE id=?1", params![item.id])?;
Ok(())
}
/// Sets the tags for an item, replacing any existing tags
///
/// # Arguments
///
/// * `conn` - Database connection
/// * `item` - Item to set tags for
/// * `tags` - Vector of tag names to set
///
/// # Returns
///
/// * `Result<()>` - Success or error if the operation fails
pub fn set_item_tags(conn: &Connection, item: Item, tags: &Vec<String>) -> Result<()> {
debug!("DB: Setting tags for item: {:?} ?{:?}", item, tags);
delete_item_tags(conn, item.clone())?;
@@ -264,6 +345,15 @@ pub fn set_item_tags(conn: &Connection, item: Item, tags: &Vec<String>) -> Resul
Ok(())
}
/// Queries all items from the database, ordered by ID
///
/// # Arguments
///
/// * `conn` - Database connection
///
/// # Returns
///
/// * `Result<Vec<Item>>` - All items in the database or an error
pub fn query_all_items(conn: &Connection) -> Result<Vec<Item>> {
debug!("DB: Querying all items");
let mut statement = conn
@@ -285,6 +375,16 @@ pub fn query_all_items(conn: &Connection) -> Result<Vec<Item>> {
Ok(items)
}
/// Queries items that have all the specified tags
///
/// # Arguments
///
/// * `conn` - Database connection
/// * `tags` - Vector of tag names to match
///
/// # Returns
///
/// * `Result<Vec<Item>>` - Matching items or an error
pub fn query_tagged_items<'a>(conn: &'a Connection, tags: &'a Vec<String>) -> Result<Vec<Item>> {
debug!("DB: Querying tagged items: {:?}", tags);
let mut statement = conn
@@ -327,11 +427,31 @@ pub fn query_tagged_items<'a>(conn: &'a Connection, tags: &'a Vec<String>) -> Re
Ok(items)
}
/// Gets all items from the database
///
/// # Arguments
///
/// * `conn` - Database connection
///
/// # Returns
///
/// * `Result<Vec<Item>>` - All items or an error
pub fn get_items(conn: &Connection) -> Result<Vec<Item>> {
debug!("DB: Getting all items");
query_all_items(conn)
}
/// Gets items matching specified tags and metadata criteria
///
/// # Arguments
///
/// * `conn` - Database connection
/// * `tags` - Vector of tag names to match
/// * `meta` - HashMap of metadata key-value pairs to match
///
/// # Returns
///
/// * `Result<Vec<Item>>` - Matching items or an error
pub fn get_items_matching(
conn: &Connection,
tags: &Vec<String>,
@@ -381,6 +501,17 @@ pub fn get_items_matching(
}
}
/// Gets a single item matching specified tags
///
/// # Arguments
///
/// * `conn` - Database connection
/// * `tags` - Vector of tag names to match
/// * `_meta` - Unused metadata parameter
///
/// # Returns
///
/// * `Result<Option<Item>>` - The matching item or None if not found, or an error
pub fn get_item_matching(
conn: &Connection,
tags: &Vec<String>,
@@ -425,6 +556,16 @@ pub fn get_item_matching(
}
}
/// Gets an item by its ID
///
/// # Arguments
///
/// * `conn` - Database connection
/// * `item_id` - ID of the item to retrieve
///
/// # Returns
///
/// * `Result<Option<Item>>` - The item if found, None if not found, or an error
pub fn get_item(conn: &Connection, item_id: i64) -> Result<Option<Item>> {
debug!("DB: Getting item {:?}", item_id);
let mut statement = conn
@@ -449,6 +590,15 @@ pub fn get_item(conn: &Connection, item_id: i64) -> Result<Option<Item>> {
}
}
/// Gets the most recently created item
///
/// # Arguments
///
/// * `conn` - Database connection
///
/// # Returns
///
/// * `Result<Option<Item>>` - The most recent item or None if no items exist, or an error
pub fn get_item_last(conn: &Connection) -> Result<Option<Item>> {
debug!("DB: Getting last item");
let mut statement = conn
@@ -474,6 +624,16 @@ pub fn get_item_last(conn: &Connection) -> Result<Option<Item>> {
}
}
/// Gets all tags for a specific item
///
/// # Arguments
///
/// * `conn` - Database connection
/// * `item` - Item to get tags for
///
/// # Returns
///
/// * `Result<Vec<Tag>>` - The item's tags or an error
pub fn get_item_tags(conn: &Connection, item: &Item) -> Result<Vec<Tag>> {
debug!("DB: Getting tags for item: {:?}", item);
let mut statement = conn
@@ -493,6 +653,16 @@ pub fn get_item_tags(conn: &Connection, item: &Item) -> Result<Vec<Tag>> {
Ok(tags)
}
/// Gets all metadata for a specific item
///
/// # Arguments
///
/// * `conn` - Database connection
/// * `item` - Item to get metadata for
///
/// # Returns
///
/// * `Result<Vec<Meta>>` - The item's metadata or an error
pub fn get_item_meta(conn: &Connection, item: &Item) -> Result<Vec<Meta>> {
debug!("DB: Getting item meta: {:?}", item);
let mut statement = conn
@@ -513,6 +683,17 @@ pub fn get_item_meta(conn: &Connection, item: &Item) -> Result<Vec<Meta>> {
Ok(metas)
}
/// Gets a specific metadata entry for an item by name
///
/// # Arguments
///
/// * `conn` - Database connection
/// * `item` - Item to get metadata for
/// * `name` - Name of the metadata field
///
/// # Returns
///
/// * `Result<Option<Meta>>` - The metadata entry if found, None if not found, or an error
pub fn get_item_meta_name(conn: &Connection, item: &Item, name: String) -> Result<Option<Meta>> {
debug!("DB: Getting item meta name: {:?} {:?}", item, name);
let mut statement = conn
@@ -530,6 +711,17 @@ pub fn get_item_meta_name(conn: &Connection, item: &Item, name: String) -> Resul
}
}
/// Gets the value of a specific metadata field for an item
///
/// # Arguments
///
/// * `conn` - Database connection
/// * `item` - Item to get metadata for
/// * `name` - Name of the metadata field
///
/// # Returns
///
/// * `Result<Option<String>>` - The metadata value if found, None if not found, or an error
pub fn get_item_meta_value(conn: &Connection, item: &Item, name: String) -> Result<Option<String>> {
debug!("DB: Getting item meta value: {:?} {:?}", item, name);
let mut statement = conn
@@ -543,6 +735,16 @@ pub fn get_item_meta_value(conn: &Connection, item: &Item, name: String) -> Resu
}
}
/// Gets tags for multiple items in a single query
///
/// # Arguments
///
/// * `conn` - Database connection
/// * `item_ids` - Slice of item IDs to get tags for
///
/// # Returns
///
/// * `Result<HashMap<i64, Vec<Tag>>>` - Mapping of item IDs to their tags, or an error
pub fn get_tags_for_items(conn: &Connection, item_ids: &[i64]) -> Result<std::collections::HashMap<i64, Vec<Tag>>> {
debug!("DB: Getting tags for items: {:?}", item_ids);
@@ -574,6 +776,16 @@ pub fn get_tags_for_items(conn: &Connection, item_ids: &[i64]) -> Result<std::co
Ok(tags_map)
}
/// Gets metadata for multiple items in a single query
///
/// # Arguments
///
/// * `conn` - Database connection
/// * `item_ids` - Slice of item IDs to get metadata for
///
/// # Returns
///
/// * `Result<HashMap<i64, HashMap<String, String>>>` - Mapping of item IDs to their metadata, or an error
pub fn get_meta_for_items(conn: &Connection, item_ids: &[i64]) -> Result<std::collections::HashMap<i64, std::collections::HashMap<String, String>>> {
debug!("DB: Getting meta for items: {:?}", item_ids);