tl;dr:

This week in Heave (2025.10.24) - The Filter Update

Hey everyone!

It’s been another busy and productive week here on the heave project. While it might feel like I was deep in the engine room, the changes I pushed this week represent a major leap forward in both functionality and the overall health of the codebase. The big theme? Giving you powerful new ways to find exactly what you need.

Let’s dive in!

The Star of the Show: A Powerful New Filtering System

The centerpiece of this week's work is the brand new load_by_filter function! I wanted to give you the ability to query your data with surgical precision, and this new feature is the answer.

You can now build complex queries to filter your items based on a wide range of conditions. I've added support for:

• Boolean: Simple true or false checks.
• Signed & Unsigned Integers: Full comparison support (=, >, <, >=, <=).
• Real Numbers (Floats): All the same numeric comparisons are supported here too!
• Text Matching: This one is really cool! You can find text that:
  • is exactly a certain string
  • starts with a substring
  • ends with a substring
  • contains a substring
• Hierarchy: You can now also filter directly by an item's class and subclass.

This opens up a world of possibilities for dynamically finding the data you need, when you need it.

Making It All Usable: A Huge Documentation Push

A powerful feature isn't very useful if no one knows how to use it! That’s why I spent a significant amount of time improving our documentation this week.

I've added crate-level documentation with a working example to get new users up and running quickly. I also beefed up the docs for all our public functions and structs, and added specific, practical examples for the new filtering system, including how to combine multiple conditions and how to work with class and subclass.

Our goal is to make heave as clear and approachable as possible, and this was a huge step in the right direction.

Under the Hood: Spring Cleaning and Refactoring

Alongside the new features, I rolled up our sleeves and did some serious housekeeping. A clean and well-organized codebase is easier to maintain and build upon.

Here’s a peek at the cleanup work:

• Better Organization: I extracted the core catalog logic and its tests into their own dedicated files. This declutters the main catalog.rs file and makes the code much easier to navigate.
• Smarter Database Queries: I refactored how I build our SQL statements to use INNER JOINs. This is a more efficient and robust way to handle queries with multiple conditions. I also added reviews and helper functions to make this part of the code cleaner and more template-driven.
• Dependency Diet: I removed some old dependencies that were only used during early development, keeping the project lean and mean.
• Code Formatting: Of course, I ran cargo fmt to keep everything neat and tidy!

These changes make the project healthier, faster, and more prepared for future features.

Staying Reliable: Fixes and Tests

Finally, what’s a new feature without tests to back it up? I added a suite of tests for the new load_by_filter and list_by_class_and_subclass functions to ensure they work exactly as expected. I also squashed a small bug in a test assertion and fixed an issue where attribute table names could clash in complex filters.

It was a fantastic week of balancing brand-new functionality with the important work of refactoring and documentation. heave is more powerful, more user-friendly, and more robust than it was seven days ago.

As always, feel free to check out the latest changes on the repository. I’d love to hear your feedback!

Until next time, happy coding

Chore

• improve justfile command with specific hour for git log
• run cargo format
• run cargo format and delete empty lines in catalog.rs
• remove useless dependencies used only during early development
• extract catalog function into their own impl file
• extract tests from catalog.rs into their own module implementation
• move Item outside of catalog test mod

Doc

• add initial documentation for load_by_filter function in catalog
• add crate level documentation with working example
• add filter example with multiple conditions
• improve documentation of publicly available functions, structs and enums
• add an example to showcase how to work with class and subclass

Feat

• add load_by_filter to catalog with possibility to filter by bool attribute
• add placeholder implementation of comparison enum to allow different comparison operators
• add signed integer filter condition with equal comparison
• add error handling during filter composition and new filter conditions for text matching
• handle comparison "greater" for signed int condition
• handle comparison "greater or equal" for signed int condition
• handle comparison "is exactly" for text condition
• handle comparison "lesser" for signed int condition
• handle comparison "lesser or equal" for signed int contidion
• handle comparisons "ends with" and "contains" for text condition
• handle comparisons =, >, <, >=, <= for unsigned int condition
• handle comparison "starts with" for text condition
• add class and subclass to filter struct
• add subclass to entity struct
• handle comparisons =, >, <, >=, <= for condition real
• add entity.subclass index to db schema

Fix

• check test assert with correct item
• set unique names for attribute table in case of multiple filter conditions

Review

• add review comments to sqlite_build_statement function
• refactor inner join fragment creation using template and helper function
• remove useless redundant tests from sqlite_load_by_filter function
• rewrite match statement for parameter building
• rewrite sqlite_build_params and remove useless tests
• use INNER JOIN to create filter statement

Test

• add test to catalog.load_by_filter function
• add tests for catalog.list_by_class_and_subclass function

tags: #rust, #devlog, #project:heave