Add the ability to load and group a child association for many parents

This is somewhat analogous to the `includes` method from Active Record.
However, it does not allow arbitrarily deep nesting. That means you can
load as many child associations for the parent as you want, but not
grandchildren or great grandchildren (you can certainly use this
infrastructure to do that, we just don't provide helpers for it out of
the box)

There's still several enhancements I'd like to make. For instance,
having to write `#[derive(Identifiable)]` feels funky, as you'd never
use that on its own. We could maybe do it on `#[derive(Queryable)]` if
the model has a field with the same name as the primary key, but that
feels really gross. Probably the best place for us to do it
automatically would be in `#[has_many]`, but that can be a separate PR.

This also does not generate the optimal query for PG, as it creates an
`IN` statement instead of `= ANY`. We eventually want to change the node
returned by `eq_any` to do the right thing for PG, but it needs
specialization to be done cleanly. Perhaps for 0.7 we can do that
optimization if `feature = "unstable"`.

This does not handle cases where the foreign key is nullable. We skip
implementing `BelongsTo` in that case, meaning the associations can be
loaded but not grouped. I have some ideas on how we can handle this in
the future, but that will be a separate PR.

I'd like to find a way to eliminate the need to specify the struct type
for the association twice. This could either be by moving
`BelongingToDsl` over to the table, or by somehow carrying the type that
the method was called on.

Finally, I think we can add an additional layer on top of this to handle
the common case of "load and group the associations without additional
filtering" into something like `users.load_associated::<Post>(&conn)`

Author: sgrif

diesel/src/associations/mod.rs

@@ -0,0 +1,32 @@
+use std::hash::Hash;
+
+pub trait Identifiable {
+    type Id: Hash + Eq + Copy;
+
+    fn id(&self) -> Self::Id;
+}
+
+pub trait BelongsTo<Parent: Identifiable> {
+    fn foreign_key(&self) -> Parent::Id;
+}
+
+pub trait GroupedBy<Parent>: IntoIterator + Sized {
+    fn grouped_by(self, parents: &[Parent]) -> Vec<Vec<Self::Item>>;
+}
+
+impl<Parent, Child> GroupedBy<Parent> for Vec<Child> where
+    Child: BelongsTo<Parent>,
+    Parent: Identifiable,
+{
+    fn grouped_by(self, parents: &[Parent]) -> Vec<Vec<Child>> {
+        use std::collections::HashMap;
+
+        let id_indices: HashMap<_, _> = parents.iter().enumerate().map(|(i, u)| (u.id(), i)).collect();
+        let mut result = parents.iter().map(|_| Vec::new()).collect::<Vec<_>>();
+        for child in self {
+            let index = id_indices[&child.foreign_key()];
+            result[index].push(child);
+        }
+        result
+    }
+}

diesel/src/expression/array_comparison.rs

@@ -1,5 +1,6 @@
 use backend::Backend;
 use expression::*;
+use expression::helper_types::SqlTypeOf;
 use query_builder::{QueryBuilder, QueryFragment, BuildQueryResult};
 use result::QueryResult;
 use types::Bool;
@@ -9,6 +10,8 @@ pub struct In<T, U> {
     values: U,
 }
 
+pub type EqAny<T, U> = In<T, <U as AsInExpression<SqlTypeOf<T>>>::InExpression>;
+
 impl<T, U> In<T, U> {
     pub fn new(left: T, values: U) -> Self {
         In {

diesel/src/expression/helper_types.rs

@@ -4,7 +4,8 @@
 use super::{Expression, AsExpression};
 use types;
 
-pub type AsExpr<Item, TargetExpr> = AsExprOf<Item, <TargetExpr as Expression>::SqlType>;
+pub type SqlTypeOf<Expr> = <Expr as Expression>::SqlType;
+pub type AsExpr<Item, TargetExpr> = AsExprOf<Item, SqlTypeOf<TargetExpr>>;
 pub type AsExprOf<Item, Type> = <Item as AsExpression<Type>>::Expression;
 
 macro_rules! gen_helper_type {
@@ -35,4 +36,7 @@ pub type Between<Lhs, Rhs> = super::predicates::Between<Lhs,
 pub type NotBetween<Lhs, Rhs> = super::predicates::NotBetween<Lhs,
     super::predicates::And<AsExpr<Rhs, Lhs>, AsExpr<Rhs, Lhs>>>;
 
+#[doc(inline)]
 pub use super::predicates::{IsNull, IsNotNull, Asc, Desc};
+#[doc(inline)]
+pub use super::array_comparison::EqAny;

diesel/src/lib.rs

@@ -9,6 +9,7 @@ mod macros;
 #[macro_use]
 pub mod query_builder;
 
+pub mod associations;
 pub mod backend;
 pub mod connection;
 #[macro_use]
@@ -72,6 +73,7 @@ pub mod helper_types {
 
 pub mod prelude {
     //! Re-exports important traits and types. Meant to be glob imported when using Diesel.
+    pub use associations::GroupedBy;
     pub use connection::Connection;
     pub use expression::{Expression, SelectableExpression, BoxableExpression};
     pub use expression::expression_methods::*;

diesel/src/query_dsl/belonging_to_dsl.rs

@@ -1,6 +1,6 @@
 use query_builder::AsQuery;
 
-pub trait BelongingToDsl<T> {
+pub trait BelongingToDsl<T: ?Sized> {
     type Output: AsQuery;
 
     fn belonging_to(other: &T) -> Self::Output;

diesel_codegen/src/associations/belongs_to.rs

@@ -10,14 +10,14 @@ use syntax::ptr::P;
 
 use model::Model;
 use super::{parse_association_options, AssociationOptions, to_foreign_key};
-use util::ty_param_of_option;
+use util::{ty_param_of_option, is_option_ty};
 
 pub fn expand_belongs_to(
     cx: &mut ExtCtxt,
     span: Span,
     meta_item: &MetaItem,
     annotatable: &Annotatable,
-    push: &mut FnMut(Annotatable)
+    push: &mut FnMut(Annotatable),
 ) {
     let options = parse_association_options("belongs_to", cx, span, meta_item, annotatable);
     if let Some((model, options)) = options {
@@ -28,9 +28,12 @@ pub fn expand_belongs_to(
             span: span,
         };
 
-        push(Annotatable::Item(belonging_to_dsl_impl(&builder)));
+        belonging_to_dsl_impl(&builder, push);
         push(Annotatable::Item(join_to_impl(&builder)));
-        for item in selectable_column_hack(&builder).into_iter() {
+        if let Some(item) = belongs_to_impl(&builder) {
+            push(Annotatable::Item(item));
+        }
+        for item in selectable_column_hack(&builder) {
             push(Annotatable::Item(item));
         }
     }
@@ -113,15 +116,18 @@ fn capitalize_from_association_name(name: String) -> String {
     result
 }
 
-fn belonging_to_dsl_impl(builder: &BelongsToAssociationBuilder) -> P<ast::Item> {
+fn belonging_to_dsl_impl(
+    builder: &BelongsToAssociationBuilder,
+    push: &mut FnMut(Annotatable),
+) {
     let parent_struct_name = builder.parent_struct_name();
     let child_struct_name = builder.child_struct_name();
     let child_table = builder.child_table();
     let foreign_key = builder.foreign_key();
     let primary_key_type = builder.primary_key_type();
     let primary_key_name = builder.primary_key_name();
 
-    quote_item!(builder.cx,
+    let item = quote_item!(builder.cx,
         impl ::diesel::BelongingToDsl<$parent_struct_name> for $child_struct_name {
             type Output = ::diesel::helper_types::FindBy<
                 $child_table,
@@ -133,7 +139,63 @@ fn belonging_to_dsl_impl(builder: &BelongsToAssociationBuilder) -> P<ast::Item>
                 $child_table.filter($foreign_key.eq(model.$primary_key_name.clone()))
             }
         }
-    ).unwrap()
+    ).unwrap();
+    push(Annotatable::Item(item));
+
+    let item = quote_item!(builder.cx,
+        impl ::diesel::BelongingToDsl<Vec<$parent_struct_name>> for $child_struct_name {
+            type Output = ::diesel::helper_types::Filter<
+                $child_table,
+                ::diesel::expression::helper_types::EqAny<
+                    $foreign_key,
+                    Vec<$primary_key_type>,
+                >,
+            >;
+
+            fn belonging_to(parents: &Vec<$parent_struct_name>) -> Self::Output {
+                let ids = parents.iter().map(|p| p.$primary_key_name.clone()).collect::<Vec<_>>();
+                $child_table.filter($foreign_key.eq_any(ids))
+            }
+        }
+    ).unwrap();
+    push(Annotatable::Item(item));
+
+    let item = quote_item!(builder.cx,
+        impl ::diesel::BelongingToDsl<[$parent_struct_name]> for $child_struct_name {
+            type Output = ::diesel::helper_types::Filter<
+                $child_table,
+                ::diesel::expression::helper_types::EqAny<
+                    $foreign_key,
+                    Vec<$primary_key_type>,
+                >,
+            >;
+
+            fn belonging_to(parents: &[$parent_struct_name]) -> Self::Output {
+                let ids = parents.iter().map(|p| p.$primary_key_name.clone()).collect::<Vec<_>>();
+                $child_table.filter($foreign_key.eq_any(ids))
+            }
+        }
+    ).unwrap();
+    push(Annotatable::Item(item));
+}
+
+fn belongs_to_impl(builder: &BelongsToAssociationBuilder) -> Option<P<ast::Item>> {
+    let parent_struct_name = builder.parent_struct_name();
+    let child_struct_name = builder.child_struct_name();
+    let primary_key_type = builder.primary_key_type();
+    let foreign_key_name = builder.foreign_key_name();
+
+    if is_option_ty(&builder.foreign_key_type()) {
+        None
+    } else {
+        Some(quote_item!(builder.cx,
+            impl ::diesel::associations::BelongsTo<$parent_struct_name> for $child_struct_name {
+                fn foreign_key(&self) -> $primary_key_type {
+                    self.$foreign_key_name
+                }
+            }
+        ).unwrap())
+    }
 }
 
 fn join_to_impl(builder: &BelongsToAssociationBuilder) -> P<ast::Item> {

diesel_codegen/src/identifiable.rs

@@ -0,0 +1,42 @@
+use syntax::ast;
+use syntax::codemap::Span;
+use syntax::ext::base::{Annotatable, ExtCtxt};
+use syntax::ext::build::AstBuilder;
+
+use model::Model;
+
+pub fn expand_derive_identifiable(
+    cx: &mut ExtCtxt,
+    span: Span,
+    _meta_item: &ast::MetaItem,
+    annotatable: &Annotatable,
+    push: &mut FnMut(Annotatable)
+) {
+    if let Some(model) = Model::from_annotable(cx, span, annotatable) {
+        let struct_name = model.name;
+        let primary_key_name = model.primary_key_name();
+        let primary_key_type = match model.attr_named(primary_key_name) {
+            Some(a) => a.ty.clone(),
+            None => {
+                let err_msg = format!(
+                    "Could not find a field named `{}` on `{}`",
+                    primary_key_name,
+                    struct_name,
+                );
+                cx.span_err(span, &err_msg);
+                return;
+            }
+        };
+
+        let item = quote_item!(cx,
+            impl ::diesel::associations::Identifiable for $struct_name {
+                type Id = $primary_key_type;
+
+                fn id(&self) -> Self::Id {
+                    self.$primary_key_name
+                }
+            }
+        ).unwrap();
+        push(Annotatable::Item(item));
+    }
+}

diesel_codegen/src/lib.in.rs

@@ -1,5 +1,6 @@
 mod associations;
 mod attr;
+mod identifiable;
 mod insertable;
 mod migrations;
 mod model;

diesel_codegen/src/lib.rs

@@ -29,6 +29,7 @@ pub fn register(reg: &mut syntex::Registry) {
     reg.add_attr("feature(custom_attribute)");
 
     reg.add_decorator("derive_Queryable", queryable::expand_derive_queryable);
+    reg.add_decorator("derive_Identifiable", identifiable::expand_derive_identifiable);
     reg.add_decorator("insertable_into", insertable::expand_insert);
     reg.add_decorator("changeset_for", update::expand_changeset_for);
     reg.add_decorator("has_many", associations::expand_has_many);
@@ -49,6 +50,10 @@ pub fn register(reg: &mut rustc_plugin::Registry) {
         intern("derive_Queryable"),
         MultiDecorator(Box::new(queryable::expand_derive_queryable))
     );
+    reg.register_syntax_extension(
+        intern("derive_Identifiable"),
+        MultiDecorator(Box::new(identifiable::expand_derive_identifiable))
+    );
     reg.register_syntax_extension(
         intern("insertable_into"),
         MultiDecorator(Box::new(insertable::expand_insert))

diesel_compile_tests/tests/compile-fail/identifiable_requires_primary_key_field.rs

@@ -0,0 +1,13 @@
+#![feature(custom_derive, custom_attribute, plugin)]
+#![plugin(diesel_codegen)]
+
+#[macro_use]
+extern crate diesel;
+
+#[derive(Identifiable)] //~ ERROR Could not find a field named `id` on `User`
+pub struct User {
+    name: String,
+    hair_color: Option<String>,
+}
+
+fn main() {}