Feat: Adds SelectStatement::apply method for functionally building query in another function

[brahmlower]

Heya! 👋 Thanks for all your work on the library- I've really enjoyed working with it! I ran into a quality of life shortcoming with the API around the SelectStatement builder: I wanted a clean way of building a portion of the query in another function, similar to the pattern used by the conditions method, but without the actual conditional part 😁

PR Info

• Closes: None

• Dependencies: None

• Dependents: None

New Features

• Added apply method to SelectStatement for constructing part of the statement from another function

  This new method is essentially a shorthand form of using the conditions function with a hardcoded value:

  // a function for building up part of the query
  fn build_query(query: &mut SelectStatement) {
      query
          .column(Users::Id)
          .from(Users::Table);
  }
  
  // The only current option is to use the `conditions` method with a hardcoded value 
  let query_count = Query::select()
      .conditions(true, build_query, |_| {})
      .to_owned();
  
  // But the code is easier to grok with the new apply method:
  let query_count = Query::select()
      .apply(build_query)
      .to_owned();

  This is useful in cases where multiple queries have the same "core" expressions, like when gathering results vs counting total query size (for pagination) on a query with joins, conditional where clauses, and groupings:

  // a function for joining the `user` and `user_external_ids` tables and filtering users
  // based on properties of their associated external ids (in this case, the system
  // name being "foo bar baz").
  fn build_query_with_filter(query: &mut SelectStatement) {
      let filter_external = true;
  
      query
          .from(Users::Table)         // the Users table
          .left_join(
              UserExternalIds::Table, // a table of related external user IDs, a many-to-one relationship with Users
              Expr::col(
                  (Users::Table, Users::Id)
              ).equals(
                  (UserExternalIds::Table, UserExternalIds::UserId)
              )
          )
          .conditions(
              filter_external,
              |q| {
                  q.and_where(Expr::col(UserExternalIds::ExternalSystem).eq("foo bar baz"));
              },
              |_| {},
          )
          .add_group_by([Expr::col(Users::Id).into()]);
  }
  
  fn main() {
      let query_count = Query::select()
          .expr(Func::count(Expr::col((Users::Table, Users::Id))))
          .apply(build_query_with_filter)
          .to_owned();
  
      let query_fetch = Query::select()
          .column(Users::Id)
          .apply(build_query_with_filter)
          .order_by(Users::CreatedAt, Order::Desc)
          .limit(10)
          .offset(0)
          .to_owned();
  }

  This is somewhat contrived example to keep it as simple as possible. For my use case, the function used to build common expressions on the query is a struct method that's referencing it's own internal state to apply the conditional filters:

   let filter = UserListFilter { ... };
  
   let query_count = Query::select()
          .expr(Func::count(Expr::col((Users::Table, Users::Id))))
          .apply(|q| filter.apply_query(q))
          .to_owned();

Bug Fixes

None

Breaking Changes

None

Changes

None as of initial authorship, however the SelectStatement::conditions method could be updated to call out to the new apply function if so desired, but it'd be a little pedantic:

    pub fn conditions<T, F>(&mut self, b: bool, if_true: T, if_false: F) -> &mut Self
    where
        T: FnOnce(&mut Self),
        F: FnOnce(&mut Self),
    {
        if b {
-            if_true(self)
+            self.apply(if_true); 
        } else {
-            if_false(self)
+            self.apply(if_false);
        }
        self
    }

[tyt2y3]

Thank you for the contribution. Can you add a doc test?

method could be updated to call out to the new apply function if so desired

I think we can leave it as is

[brahmlower]

Can you add a doc test?

Oh absolutely! In hindsight it's pretty obvious that I should have included that in the first place 😅 I'll start working on that now, should have it pushed relatively soon

[brahmlower]

Mkay I've added the doctest example. I just copied and updated the example used for conditionals for the sake of consistency, but I'm happy to make changes if you'd prefer something different 👍

[brahmlower]

Hey @tyt2y3 👋 I just wanted to check in to see if there were any other concerns with this PR?

[tyt2y3]

Hi! Just came back. Happy new year!

[github-actions]

🎉 Released In 0.30.7 🎉

Thank you everyone for the contribution!
This feature is now available in the latest release. Now is a good time to upgrade!
Your participation is what makes us unique; your adoption is what drives us forward.
You can support SeaQL 🌊 by starring our repos, sharing our libraries and becoming a sponsor ⭐.

[brahmlower]

Hey thanks for merging this yesterday! Didn't intend to rush ya, so sorry about that- hope you had a good break, and happy new year to you too! 🥳