Allow complex queries with table joins

[xjunior]

Allow using external columns for complex joins. In the bellow example we're able to query the user membership within a group:

  class User < ApplicationRecord
    has_and_belongs_to_many :groups

    def self.scim_queryable_attributes
      return {
        'groups'       => { column: Group.arel_table[:id] },
        'groups.value' => { column: Group.arel_table[:id] },
      }
    end
  end

Then:

  class UsersController < Scimitar::ActiveRecordBackedResourcesController
    def storage_class
      ::User
    end

    def storage_scope
      ::User.left_joins(:groups)
    end
  end

[pond]

Sorry to get to this so late.

The code looks good and I'm very enthusiastic about your test coverage. The only missing thing is documentation - sorry, can be tedious, but it's super-important. New features need clear and comprehensive documentation in README.md, otherwise nobody knows the feature exists and future maintainers risk stumbling across code with no apparent purpose.

It looks like a subsection addition under ### Controllers at (v2.4.3) line 224. The important part is ideally not to just give the example in the PR description, but to explain what's really happening. We know, because we know how the under-hood implementation works. Regular gem users won't.

• You have a User join in storage_scope
• You have a scim_queryable_attributes with Group.arel_table[:id]
• Please make sure the reader understands in particular why there's the magic arel_table[:id] there.

The reader wants to understand what this feature is for and how it would work for them with their own data model, so that's why it's not good to force the reader to rely on assumptions and guesswork (e.g. be very clear that you have a run-of-the-mill ApplicationRecord-based User model with a belongs_to - or is it HABTM? - relationship to another run-of-the-mill ApplicationRecord-based Group model).

Hope that's OK.

[pond]

Again is all good except docs - AREL use still not explained - see review comment for a suggestion about putting that into the RDoc comments of the mixin.

(Edited to note - I'm definitely really keen to get this merged, I just wanna make sure people know how to use it).

[xjunior]

@pond let me know how you feel about the changes. I expanded the options documentation a bit, allowing us to introduce more queryable attribute options in the future (I can see a case_sensitive option, for instance).

[pond]

The comment additions are enough. The options docs aren't really RDoc, but I'll clean that up before releasing the bumped gem version. This is good to go!

[pond]

Formatting & RDoc markup tweaks can be seen in the diff at https://github.com/RIPAGlobal/scimitar/pull/67/files - hope you're OK with those changes; let me know if not (e.g. comment on that PR, even if it's merged).

Edited to add - screenshot of RDoc rendering: