Support custom filters

[matthewdias]

It would be very useful to support custom filter params that can be passed to scopes. Similar to http://jsonapi-resources.com/v0.10/guide/resources.html#Applying-Filters

[zacharygolba]

I agree this would be great. I imagine the API would look something like this:

import { Controller } from 'lux-framework'

class UsersController extends Controller {
  filter = {
    /**
     * @param query Query - The instance of the query builder dsl
     * @param value string - The deserialized value from the param in the url
     */
    fullName: (query, value) => {
      const [firstName, lastName] = value.split(' ')

      return query.where({
        firstName,
        lastName,
      })
    },
  }
}

Ideally this would be backwards compatible with the current filter property in the Controller API which is just an array of strings used to whitelist property names. We could expand values using the old API upon application boot. The "de-sugared" implementation could look something like the following example:

import { Controller } from 'lux-framework'

/**
 * A naive implementation of how Lux could internally transform
 * strings in a filter array into functions that use the new API.
 */
const eq = (key) => (query, value) => query.where({
  [key]: value,
})

/**
 * Before Expansion
 */
class UsersController extends Controller {
  filter = [
    'isAdmin',
    'firstName',
    'lastName',
  ]
}

/**
 * After Expansion
 */
class UsersController extends Controller {
  filter = {
    isAdmin: eq('isAdmin'),
    firstName: eq('firstName'),
    lastName: eq('isAdmin'),
  }
}

This still needs a bit of thought regarding whether or not the default filters are implicitly added to the filter object amongst other things like exposing utility functions to help with composing custom filters.

Any thoughts on how the public API would look for this feature? My examples above are really just brainstorming.

cc @aortbals @nickschot @jamemackson

[zacharygolba]

Also, this is related to #699.

@willviles do you have any thoughts regarding this feature?

[willviles]

@zacharygolba @matthewdias - I really like the idea of custom filter params. The suggested API looks great.

With regard to #699, I suppose that's down to whether we think filtering by relationship values should work out-of-the-box, or require a level of explicit configuration.

Consider the example I give in #699, finding users by their permission id: /users?filter[permission]=2,4. Pretty simple right?

import { Controller } from 'lux-framework'

class UsersController extends Controller {
  filter = {
    permission: (query, value) => {
      let ids = [value.split(',')];
      return query.where({
        permissionId: ids
      });
    }
  }
}

Adding >, <, >= & <= comparison operators is a little more effort. Here's a pretty quick attempt at how it may look...

import { Controller } from 'lux-framework'

class UsersController extends Controller {
  filter = {
    permission: (query, value) => {
      let modifier = value.match(/[<>]=?/gA);
      if (modifier.length) {
        let id = value.replace(modifier[0], '');
        return query.whereRaw(`permissionId ${modifier[0]} ?`, [value]);
      } else {
        let ids = [value.split(',')];
        return query.where({
          permissionId: ids
        });
      }
    }
  }
}

As for filtering by relationship attributes, such as /articles?filter[tags][name]=foo, that's much more difficult. However, it'd be nice to have a pattern for it without writing raw custom SQL queries.

I like the idea that filters could be implemented in a similar way to computed properties in Ember. Perhaps we could do something like so:

import { Controller, filters } from 'lux-framework';

const { 
  belongsTo, 
  eq, 
  hasMany 
} = filters;

class UsersController extends Controller {
  filter = {
    isAdmin: eq('isAdmin'),
    permission: belongsTo('permission'), 
    tags: hasMany('tag')
  }
}

belongsTo and hasMany would ensure we look for the right relationship key (permissionId and tagIds in this instance).

We could even include a final param options hash to enable/disable aspects of advanced filtering.

permission: belongsTo('permission', { operators: true })

[matthewdias]

Relationship filtering and comparative operators out of the box sounds 👌 to me. We'll need to maintain the functionality of specifying which filters are allowed. Maybe configurable for the related resource, and allowed to be overridden on the parent resource? Also curious about thoughts on ?filter[tags][name]=foo vs ?filter[tags.name]=foo. Seems the latter would line up better with inclusion and sorting. (I haven't actually used Lux extensively yet, so I'm just assuming those work that way. Please correct me if I'm wrong.)

[willviles]

I tend to agree that filtering by relationship ids/comparative operators should come out of the box.

As for using filters on the related resource, that's a great idea. So /articles?filter[tags][name]=foo would hit the ArticlesController, see we're wanting to filter by related tags and then use the name filter in the TagsController. Alternatively, the following in the ArticlesController could override the filter:

filter = {
  tags: {
    name(query, value) {
      return ...;
    }
  }
}

Btw, Ember JSONAPISerializer serializes nested filters as filter[tags][name]=foo, so perhaps we stick to that syntax?

Also, if we're enabling related record filtering, do you think there's value in offering a nice way of sorting on related record values?