rokaki 0.7.0 → 0.8.0.pre.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a46db4e821b0a8fb7f661ed539c18c6509b0a644b3bc0f790c0619ab72ff4108
-  data.tar.gz: f6ae9809a6a82c9a1de24ecf7d79b9f0cc6cab530579751df919832c0fa3593e
+  metadata.gz: cd7982d23aa428243393be242a44e66655f3805cd23e2cb75e9f9ac1d9f6e8a3
+  data.tar.gz: 07d183020e8234b19d253cbde9172a3d802a705be0e535d982c6be06087ab3a5
 SHA512:
-  metadata.gz: 55b11eee1380defcbd8b56e584b4d4ea145571718da3fa82e5445b2233d779bf169c173d19f5afbf5e7eb6dc69a070a8a08ff64fa3dc41fc4d29690ab2de0556
-  data.tar.gz: 88869cad8ba114234d2581661277963d3eb2effd4aecded8be6d2b7140dcb8331b68d529b4e388518c8ca503deff5f5b8ede87d33bb98152c8e29f676eb268ba
+  metadata.gz: 8a22d6928e09c881f021e16b92bffa57f43f8a872528ab49f1b25f5ffc0c0a5918898944ea41439ed58d5e1fa1a40fbc16cbc6fa628f7380680cc2cc1bc3abe2
+  data.tar.gz: 8e9ac460a085d3bc32b72cb9b9d1c6198da65bae3e6d76a03a916708faa2e5862c3102d66407b795c23c93e4b527ea5fbda190d93ae876a583253d8b18d08ce7

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rokaki (0.6.0)
+    rokaki (0.7.0)
       activesupport
 
 GEM
@@ -22,6 +22,8 @@ GEM
     coderay (1.1.2)
     concurrent-ruby (1.1.5)
     diff-lcs (1.3)
+    factory_bot (5.1.1)
+      activesupport (>= 4.2.0)
     ffi (1.11.1)
     formatador (0.2.5)
     guard (2.15.0)
@@ -90,6 +92,7 @@ PLATFORMS
 DEPENDENCIES
   activerecord
   bundler (~> 2.0)
+  factory_bot
   guard
   guard-rspec
   pg
@@ -101,4 +104,4 @@ DEPENDENCIES
   sqlite3
 
 BUNDLED WITH
-   2.0.2
+   2.1.3

data/README.md

@@ -1,10 +1,9 @@
 # Rokaki
 [![Gem Version](https://badge.fury.io/rb/rokaki.svg)](https://badge.fury.io/rb/rokaki)
 
-This gem was born out of a desire to dry up filtering services in Rails or any ruby app that uses the concept of `filters`.
-
-It's a simple gem that just provides you with a basic dsl based on the filter params that you might pass through from a web request.
+This gem was born out of a desire to dry up filtering services in Rails apps or any Ruby app that uses the concept of "filters" or "facets".
 
+There are two modes of use `Filterable` and `FilterModel` that can be activated through the use of two mixins respectively, `include Rokaki::Filterable` or `include Rokaki::FilterModel`.
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -17,42 +16,118 @@ And then execute:
 
     $ bundle
 
-## Usage
+## `Rokaki::Filterable` - Usage
+
+To use the DSL first include the `Rokaki::Filterable` module in your [por](http://blog.jayfields.com/2007/10/ruby-poro.html) class.
 
-To use the basic DSL include the `Rokaki::Filterable` module
+### `#define_filter_keys`
+#### A Simple Example
 
 A simple example might be:-
 
 ```ruby
-  class FilterArticles
-    include Rokaki::Filterable
+class FilterArticles
+  include Rokaki::Filterable
 
-    def initialize(filters:)
-      @filters = filters
-      @articles = Article
-    end
+  def initialize(filters:)
+    @filters = filters
+    @articles = Article
+  end
 
-    attr_accessor :filters
+  attr_accessor :filters
 
-    define_filter_keys :date, author: [:first_name, :last_name]
+  define_filter_keys :date, author: [:first_name, :last_name]
 
-    def filter_results
-      @articles = @articles.where(date: date) if date
-      @articles = @articles.joins(:author).where(author: { first_name: author_first_name }) if author_first_name
-    end
+  def filter_results
+    @articles = @articles.where(date: date) if date
+    @articles = @articles.joins(:author).where(author: { first_name: author_first_name }) if author_first_name
   end
+end
+
+article_filter = FilterArticles.new(filters: {
+  date: '10-10-10',
+  author: {
+    first_name: 'Steve',
+    last_name: 'Martin'
+  }})
+article_filter.author_first_name == 'Steve'
+article_filter.author_last_name == 'Martin'
+article_filter.date == '10-10-10'
+```
+
+In this example Rokaki maps the "flat" attribute "keys" `date`, `author_first_name` and `author_last_name` to a `@filters` object with the expected deep structure `{ date: '10-10-10', author: { first_name: 'Steve' } }`, to make it simple to use them in filter queries.
+
+#### A More Complex Example
+
+```ruby
+class AdvancedFilterable
+  include Rokaki::Filterable
+
+  def initialize(filters:)
+    @fyltrz = filters
+  end
+  attr_accessor :fyltrz
+
+  filterable_object_name :fyltrz
+  filter_key_infix :__
+  define_filter_keys :basic, advanced: {
+    filter_key_1: [:filter_key_2, { filter_key_3: :deep_node }],
+    filter_key_4: :deep_leaf_array
+  }
+end
+
+
+advanced_filterable = AdvancedFilterable.new(filters: {
+  basic: 'ABC',
+  advanced: {
+    filter_key_1: {
+      filter_key_2: '123',
+      filter_key_3: { deep_node: 'NODE' }
+    },
+    filter_key_4: { deep_leaf_array: [1,2,3,4] }
+  }
+})
+
+advanced_filterable.advanced__filter_key_4__deep_leaf_array == [1,2,3,4]
+advanced_filterable.advanced__filter_key_1__filter_key_3__deep_node == 'NODE'
 ```
+### `#define_filter_map`
 
-This maps attributes `date`, `author_first_name` and `author_last_name` to a filters object with the structure `{ date: '10-10-10', author: { first_name: 'Shteeve' } }`.
+This method takes a single field in the passed in filters hash and maps it to fields named in the second param, this is useful if you want to search for a single value across many different fields or associated tables simultaneously.
 
-## Additional options
-You can specify a `filter_key_prefix` and a `filter_key_infix` to change the structure of the accessors.
+#### A Simple Example
+```ruby
+class FilterMap
+  include Rokaki::Filterable
+
+  def initialize(fylterz:)
+    @fylterz = fylterz
+  end
+  attr_accessor :fylterz
+
+  filterable_object_name :fylterz
+  define_filter_map :query, :mapped_a, association: :field
+end
+
+filter_map = FilterMap.new(fytlerz: { query: 'H2O' })
+
+filter_map.mapped_a == 'H2O'
+filter_map.association_field = 'H2O'
+```
+
+#### Additional `Filterable` options
+You can specify several configuration options, for example a `filter_key_prefix` and a `filter_key_infix` to change the structure of the generated filter accessors.
 
 `filter_key_prefix :__` would result in key accessors like `__author_first_name`
 
 `filter_key_infix :__` would result in key accessors like `author__first_name`
 
-## ActiveRecord
+`filterable_object_name :fylterz` would use an internal filter state object named `@fyltrz` instead of the default `@filters`
+
+
+## `Rokaki::FilterModel` - Usage
+
+### ActiveRecord
 Include `Rokaki::FilterModel` in any ActiveRecord model (only AR >= 6.0.0 tested so far) you can generate the filter keys and the actual filter lookup code using the `filters` keyword on a model like so:-
 
 ```ruby
@@ -67,7 +142,7 @@ end
 
 
 class ArticleFilter
-  include FilterModel
+  include Rokaki::FilterModel
 
   filters :date, :title, author: [:first_name, :last_name]
 
@@ -96,7 +171,7 @@ You can use `like` (or, if you use postgres, the case insensitive `ilike`) to pe
 
 ```ruby
 class ArticleFilter
-  include FilterModel
+  include Rokaki::FilterModel
 
   filter :article,
     like: { # you can use ilike here instead if you use postgres and want case insensitive results
@@ -122,7 +197,7 @@ In this syntax you will need to provide three keywords:- `filters`, `like` and `
 
 ```ruby
 class ArticleFilter
-  include FilterModel
+  include Rokaki::FilterModel
 
   filters :date, :title, author: [:first_name, :last_name]
   like title: :circumfix
@@ -141,7 +216,7 @@ Or without the model in the initializer
 
 ```ruby
 class ArticleFilter
-  include FilterModel
+  include Rokaki::FilterModel
 
   filters :date, :title, author: [:first_name, :last_name]
   like title: :circumfix
@@ -165,7 +240,7 @@ Would produce a query with a LIKE which circumfixes '%' around the filter term,
 You can filter joins both with basic matching and partial matching
 ```ruby
 class ArticleFilter
-  include FilterModel
+  include Rokaki::FilterModel
 
   filter :author,
     like: {
@@ -189,6 +264,8 @@ You can pass array params (and partially match them), to filters (search multipl
 
 ```ruby
 class ArticleFilter
+  include Rokaki::FilterModel
+
   filter :article,
     like: {
       author: {

data/lib/rokaki/filterable.rb

@@ -16,6 +16,13 @@ module Rokaki
         end
       end
 
+      def define_filter_map(query_field, *filter_keys)
+        filter_keys.each do |filter_key|
+          _map_filters(query_field, [filter_key]) unless filter_key.is_a? Hash
+          _nested_map query_field, filter_key if filter_key.is_a? Hash
+        end
+      end
+
       def filter_key_prefix(prefix = nil)
         @filter_key_prefix ||= prefix
       end
@@ -24,6 +31,10 @@ module Rokaki
         @filter_key_infix ||= infix
       end
 
+      def filterable_object_name(name = 'filters')
+        @filterable_object_name ||= name
+      end
+
       def _build_filter(keys)
         name    = @filter_key_prefix.to_s
         count   = keys.size - 1
@@ -33,12 +44,30 @@ module Rokaki
           name += filter_key_infix.to_s unless count == i
         end
 
-        class_eval "def #{name}; filters.dig(*#{keys}); end;", __FILE__, __LINE__
+        class_eval "def #{name}; #{filterable_object_name}.dig(*#{keys}); end;", __FILE__, __LINE__
+      end
+
+      def _map_filters(query_field, keys)
+        name    = @filter_key_prefix.to_s
+        count   = keys.size - 1
+
+        keys.each_with_index do |key, i|
+          name += key.to_s
+          name += filter_key_infix.to_s unless count == i
+        end
+
+        class_eval "def #{name}; #{filterable_object_name}.dig(:#{query_field}); end;", __FILE__, __LINE__
       end
 
       def _nested_key(filters_object)
         filters_object.keys.each do |key|
-          deep_map([key], filters_object[key])
+          deep_map([key], filters_object[key]) { |keys| _build_filter(keys) }
+        end
+      end
+
+      def _nested_map(query_field, filters_object)
+        filters_object.keys.each do |key|
+          deep_map([key], filters_object[key]) { |keys| _map_filters(query_field, keys) }
         end
       end
 
@@ -46,20 +75,24 @@ module Rokaki
         if value.is_a? Hash
           value.keys.map do |key|
             _keys = keys.dup << key
-            deep_map(_keys, value[key])
+            deep_map(_keys, value[key], &Proc.new)
           end
         end
 
         if value.is_a? Array
           value.each do |av|
+            if av.is_a? Symbol
             _keys = keys.dup << av
-            _build_filter(_keys)
+            yield _keys
+            else
+              deep_map(keys, av, &Proc.new)
+            end
           end
         end
 
         if value.is_a? Symbol
           _keys = keys.dup << value
-          _build_filter(_keys)
+          yield _keys
         end
       end
 

data/lib/rokaki/version.rb

@@ -1,3 +1,3 @@
 module Rokaki
-  VERSION = "0.7.0"
+  VERSION = "0.8.0-pre"
 end

data/rokaki.gemspec

@@ -34,12 +34,13 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency 'activerecord'
   spec.add_development_dependency 'bundler', '~> 2.0'
+  spec.add_development_dependency 'factory_bot'
   spec.add_development_dependency 'guard'
   spec.add_development_dependency 'guard-rspec'
+  spec.add_development_dependency 'pg'
   spec.add_development_dependency 'pry'
   spec.add_development_dependency 'pry-byebug'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'sqlite3'
-  spec.add_development_dependency 'pg'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rokaki
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0.pre.pre
 platform: ruby
 authors:
 - Steve Martin
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-11-09 00:00:00.000000000 Z
+date: 2020-04-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -52,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: factory_bot
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: guard
   requirement: !ruby/object:Gem::Requirement
@@ -80,6 +94,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -150,20 +178,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: pg
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 description: A dsl for filtering data in web requests
 email:
 - steve@martian.media
@@ -208,11 +222,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
-rubygems_version: 3.0.4
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: A web request filtering library