rokaki 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dcbf82920cbfeff8466f6ccd583f1a66652082e087c2d6641806be8720dd8d6c
-  data.tar.gz: 4165d387e1fba3820fc302ef414f0019077067a1dca7d307943030f0aec99207
+  metadata.gz: 2659a359499939511a45107cc281e2aecce654ecf587f668e9de52d6fd8e3424
+  data.tar.gz: 4a5dfa2b6eef83fb731bb558575bdd5072b2c5ff2f4dc3670b11cae9487447ff
 SHA512:
-  metadata.gz: 8e5d866b175e0799ad9bff2cbb8660e8ebca48785e508223e7583452eb7e95e56c1c35f15ff8625fc456365651b82efff40636579f90469d9909f650f6ee2b1d
-  data.tar.gz: e974f32a7626a94fb618295ea9600e9747af73bd35986f9e843a81b4bc6168c98180ef85d150fc1ad96ff4fa4700daae5d16d75596bc2d3dd9279ba8d6a98c64
+  metadata.gz: a120036a6621d1ca69631d95fccd5fa3fac82cbb4a630bffcc5a5ea87ec026ef416fda109964eec929d1c8874af7a4dc08e06bab2cd1789779332ae9796b645e
+  data.tar.gz: 656df3353ae9593cdeaa75ce0b0111728fbbb420d8c4885928fcc334369ceaa07ea09f78a49b93b3ab45ea8d5767b81f9280cd9cf55260690a0a34270947c7ab

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+### 0.13.0 — 2025-10-25
+- Add block-form DSL parity across both FilterModel and Filterable (`filter_map do ... end` with `like`, `ilike`, `nested`, and `filters`).
+- Support circumfix affix synonyms: `:parafix`, `:confix`, `:ambifix` (treated as `:circumfix`).
+- Improve docs with block-form examples and adapter behavior notes.
+- Keep SQL Server support (introduced earlier) covered in CI; add shared tests for affix synonyms to all adapter-aware specs.
+- Allow ENV overrides for all adapters in test DatabaseManager (Postgres/MySQL/SQL Server).
+
+### 0.12.0 — 2025-10-25
+- Introduce block-form DSL for FilterModel (`filter_map do ... end`) with `like` and `nested`.
+- Update docs site and GitHub Pages build.
+
+### 0.11.0 — 2025-10-25
+- Add first-class SQL Server support.
+- CI updates to run tests against SQL Server, alongside PostgreSQL and MySQL.
+
+### 0.10.0 and earlier
+- Core DSL: Filterable and FilterModel modes, LIKE matching with prefix/suffix/circumfix, nested filters, and adapter-aware SQL for Postgres/MySQL.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rokaki (0.12.0)
+    rokaki (0.13.0)
       activesupport
 
 GEM

data/docs/index.md

@@ -21,7 +21,7 @@ Get started below or jump to:
 Add to your application's Gemfile:
 
 ```ruby
-gem "rokaki", "~> 0.11"
+gem "rokaki", "~> 0.13"
 ```
 
 Then:
@@ -32,7 +32,9 @@ bundle install
 
 ## Quick start
 
-Use `Rokaki::FilterModel` and declare mappings with method arguments (no block DSL).
+You can declare mappings in two ways: argument-based (original) or block-form DSL. Both are equivalent.
+
+Argument-based form:
 
 ```ruby
 class ArticleQuery
@@ -58,6 +60,34 @@ end
 filtered = ArticleQuery.new(filters: params).results
 ```
 
+Block-form DSL (same behavior):
+
+```ruby
+class ArticleQuery
+  include Rokaki::FilterModel
+
+  filter_model :article, db: :postgres # or :mysql, :sqlserver
+  define_query_key :q
+
+  filter_map do
+    like title: :circumfix, content: :circumfix
+    nested :author do
+      like first_name: :prefix, last_name: :suffix
+      # You can also declare equality filters inside nested contexts
+      filters :id
+    end
+  end
+
+  attr_accessor :filters
+  def initialize(filters: {})
+    @filters = filters
+  end
+end
+
+# In a controller/service:
+filtered = ArticleQuery.new(filters: params).results
+```
+
 Where `params` can include keys like `q`, `author_first_name`, `author_last_name`, etc. The LIKE mode for each key is defined in your `like` mapping (e.g., `title: :circumfix`), and Rokaki builds the appropriate `WHERE` clauses safely and adapter‑aware.
 
 ## Matching modes
@@ -68,6 +98,14 @@ Where `params` can include keys like `q`, `author_first_name`, `author_last_name
 
 All modes accept either a single string or an array of terms.
 
+## What’s new in 0.13.0
+
+- Block-form DSL parity across both FilterModel and Filterable
+- Circumfix affix synonyms supported: :parafix, :confix, :ambifix
+- SQL Server adapter support and CI coverage
+- ENV overrides for all adapters in test helpers; improved DB bootstrap in specs
+- Documentation site via GitHub Pages
+
 ## Next steps
 
 - Learn the full DSL and examples in [Usage](./usage)

data/docs/usage.md

@@ -11,7 +11,7 @@ This page shows how to use Rokaki to define filters and apply them to ActiveReco
 Add the gem to your Gemfile and bundle:
 
 ```ruby
-gem "rokaki", "~> 0.11"
+gem "rokaki", "~> 0.13"
 ```
 
 ```bash
@@ -38,7 +38,7 @@ class ArticleQuery
   define_query_key :q
   like title: :circumfix, content: :circumfix
 
-  # Nested LIKEs via hash mapping (no block DSL)
+  # Nested LIKEs via hash mapping
   like author: { first_name: :prefix, last_name: :suffix }
 end
 ```
@@ -98,3 +98,91 @@ Params would include `author_first`, `author_first_prefix`, etc.
 - Use `key:` to map a filter to a different params key.
 - Combine multiple filters; Rokaki composes them with `AND` by default.
 - For advanced cases, write custom filters in your app by extending the DSL (see source for `BasicFilter`/`NestedFilter`).
+
+
+## Block-form DSL
+
+Note: The block-form DSL is available starting in Rokaki 0.13.0.
+
+Rokaki also supports a block-form DSL that is equivalent to the argument-based form. Use it when you prefer grouping your mappings in a single block.
+
+### FilterModel block form
+
+```ruby
+class ArticleQuery
+  include Rokaki::FilterModel
+
+  # Choose model and adapter
+  filter_model :article, db: :postgres # or :mysql, :sqlserver
+
+  # Declare a single query key used by all LIKE/equality filters below
+  define_query_key :q
+
+  # Declare mappings inside a block
+  filter_map do
+    # LIKE mappings on the base model
+    like title: :circumfix, content: :circumfix
+
+    # Nested mappings on associations
+    nested :author do
+      like first_name: :prefix, last_name: :suffix
+
+      # You can also declare equality filters in block form
+      filters :id
+    end
+  end
+
+  attr_accessor :filters
+  def initialize(filters: {})
+    @filters = filters
+  end
+end
+
+# Usage
+ArticleQuery.new(filters: { q: ["Intro", "Guide"] }).results
+```
+
+Notes:
+- Modes are declared by the values in your `like` mapping (`:prefix`, `:suffix`, `:circumfix`). Synonyms `:parafix`, `:confix`, `:ambifix` behave like `:circumfix`.
+- Arrays for `q` are supported across adapters. PostgreSQL uses `ANY (ARRAY[...])`, MySQL/SQL Server expand to OR chains as appropriate.
+
+### Filterable block form
+
+Use the block form to define simple key accessors (no SQL). Useful for plain Ruby objects or when building a mapping layer.
+
+```ruby
+class ArticleFilters
+  include Rokaki::Filterable
+  filter_key_prefix :__
+
+  filter_map do
+    filters :date, author: [:first_name, :last_name]
+
+    nested :author do
+      nested :location do
+        filters :city
+      end
+    end
+  end
+
+  # Expect a #filters method that returns a hash
+  attr_reader :filters
+  def initialize(filters: {})
+    @filters = filters
+  end
+end
+
+f = ArticleFilters.new(filters: {
+  date: '2025-01-01',
+  author: { first_name: 'Ada', last_name: 'Lovelace', location: { city: 'London' } }
+})
+
+f.__date                        # => '2025-01-01'
+f.__author__first_name          # => 'Ada'
+f.__author__last_name           # => 'Lovelace'
+f.__author__location__city      # => 'London'
+```
+
+Tips:
+- `filter_key_prefix` and `filter_key_infix` control the generated accessor names.
+- Inside the block, `nested :association` affects all `filters` declared within it.

data/lib/rokaki/filter_model.rb

@@ -120,7 +120,72 @@ module Rokaki
         end
       end
 
-      def filter_map(model, query_key, options)
+      # Merge two nested like/ilike mappings
+      def deep_merge_like(a, b)
+        return b if a.nil? || a == {}
+        return a if b.nil? || b == {}
+        a.merge(b) do |_, v1, v2|
+          if v1.is_a?(Hash) && v2.is_a?(Hash)
+            deep_merge_like(v1, v2)
+          else
+            # Prefer later definitions
+            v2
+          end
+        end
+      end
+
+      # Wrap a normalized mapping with current nested context stack
+      def wrap_in_context(mapping)
+        return mapping if !@__ctx_stack || @__ctx_stack.empty?
+        @__ctx_stack.reverse.inject(mapping) { |acc, key| { key => acc } }
+      end
+
+      # Block DSL: nested context for like/ilike within filter_map block
+      def nested(name, &blk)
+        if instance_variable_defined?(:@__in_filter_map_block) && @__in_filter_map_block
+          raise ArgumentError, 'nested requires a symbol name' unless name.is_a?(Symbol)
+          @__ctx_stack << name
+          instance_eval(&blk) if blk
+          @__ctx_stack.pop
+        else
+          raise NoMethodError, 'nested can only be used inside filter_map block'
+        end
+      end
+
+      def filter_map(*args, &block)
+        # Block form: requires prior calls to filter_model and define_query_key
+        if block_given? && args.empty?
+          raise ArgumentError, 'define_query_key must be called before block filter_map' unless @filter_map_query_key
+          raise ArgumentError, 'filter_model must be called before block filter_map' unless @model
+          @_filter_db ||= :postgres
+
+          # Enter block-collection mode
+          @__in_filter_map_block = true
+          @__block_like_accumulator = {}
+          @__block_ilike_accumulator = {}
+          @__ctx_stack = []
+
+          instance_eval(&block)
+
+          # Exit and materialize definitions
+          @__in_filter_map_block = false
+          unless @__block_like_accumulator.empty?
+            like(@__block_like_accumulator)
+          end
+          unless @__block_ilike_accumulator.empty?
+            ilike(@__block_ilike_accumulator)
+          end
+
+          # cleanup
+          @__block_like_accumulator = nil
+          @__block_ilike_accumulator = nil
+          @__ctx_stack = nil
+
+          return
+        end
+
+        # Positional/legacy form
+        model, query_key, options = args
         filter_model(model)
         @filter_map_query_key = query_key
 
@@ -143,6 +208,12 @@ module Rokaki
       end
 
       def filters(*filter_keys)
+        # In block form for FilterModel, allow equality filters inside nested contexts
+        if instance_variable_defined?(:@__in_filter_map_block) && @__in_filter_map_block
+          wrapped_keys = filter_keys.map { |fk| wrap_in_context(fk) }
+          filter_keys = wrapped_keys
+        end
+
         if @filter_map_query_key
           define_filter_map(@filter_map_query_key, *filter_keys)
         else
@@ -276,6 +347,12 @@ module Rokaki
 
       def like(args)
         raise ArgumentError, 'argument mush be a hash' unless args.is_a? Hash
+        if instance_variable_defined?(:@__in_filter_map_block) && @__in_filter_map_block
+          normalized = normalize_like_modes(args)
+          @__block_like_accumulator = deep_merge_like(@__block_like_accumulator, wrap_in_context(normalized))
+          return
+        end
+
         normalized = normalize_like_modes(args)
         @_like_semantics = (@_like_semantics || {}).merge(normalized)
 
@@ -285,6 +362,12 @@ module Rokaki
 
       def ilike(args)
         raise ArgumentError, 'argument mush be a hash' unless args.is_a? Hash
+        if instance_variable_defined?(:@__in_filter_map_block) && @__in_filter_map_block
+          normalized = normalize_like_modes(args)
+          @__block_ilike_accumulator = deep_merge_like(@__block_ilike_accumulator, wrap_in_context(normalized))
+          return
+        end
+
         normalized = normalize_like_modes(args)
         @i_like_semantics = (@i_like_semantics || {}).merge(normalized)
 

data/lib/rokaki/filterable.rb

@@ -13,6 +13,48 @@ module Rokaki
     module ClassMethods
       private
 
+      # --- Block DSL support (Filterable mode) ---
+      def nested(name, &blk)
+        if instance_variable_defined?(:@__in_filterable_block) && @__in_filterable_block
+          raise ArgumentError, 'nested requires a symbol name' unless name.is_a?(Symbol)
+          @__ctx_stack << name
+          instance_eval(&blk) if blk
+          @__ctx_stack.pop
+        else
+          raise NoMethodError, 'nested can only be used inside filter_map block'
+        end
+      end
+
+      # In Filterable, `filter_map` without args opens a block to declare `filters` with optional nesting
+      # For backward compatibility, if args are provided, delegate to define_filter_map
+      def filter_map(*args, &block)
+        if block_given? && args.empty?
+          # Enter block-collection mode
+          @__in_filterable_block = true
+          @__ctx_stack = []
+          @__block_filters = []
+
+          instance_eval(&block)
+
+          # Materialize collected filters
+          unless @__block_filters.empty?
+            define_filter_keys(*@__block_filters)
+          end
+
+          # cleanup
+          @__in_filterable_block = false
+          @__ctx_stack = nil
+          @__block_filters = nil
+          return
+        end
+
+        # Positional/legacy map form (delegates to define_filter_map)
+        if args.any?
+          query_field, *filter_keys = args
+          define_filter_map(query_field, *filter_keys)
+        end
+      end
+
       def define_filter_keys(*filter_keys)
         filter_keys.each do |filter_key|
           _build_filter([filter_key]) unless Hash === filter_key
@@ -96,8 +138,8 @@ module Rokaki
         if value.is_a? Array
           value.each do |av|
             if av.is_a? Symbol
-            _keys = keys.dup << av
-            yield _keys
+              _keys = keys.dup << av
+              yield _keys
             else
               deep_map(keys, av, &block)
             end
@@ -110,6 +152,33 @@ module Rokaki
         end
       end
 
+      # Helper: wrap a Symbol/Hash filter key in current nested context
+      def wrap_in_context(filter_key)
+        return filter_key unless instance_variable_defined?(:@__ctx_stack) && @__ctx_stack && !@__ctx_stack.empty?
+        ctx = @__ctx_stack.dup
+        if filter_key.is_a?(Hash)
+          # Nest the entire hash under the context chain
+          ctx.reverse.inject(filter_key) { |acc, k| { k => acc } }
+        else
+          # Symbol → build a hash with leaf
+          ctx.reverse.inject(filter_key) { |acc, k| { k => acc } }
+        end
+      end
+
+      public
+
+      # Enhance `filters` to support block mode accumulation
+      def filters(*filter_keys)
+        if instance_variable_defined?(:@__in_filterable_block) && @__in_filterable_block
+          filter_keys.each do |fk|
+            @__block_filters << wrap_in_context(fk)
+          end
+          return
+        end
+
+        define_filter_keys(*filter_keys)
+      end
+
     end
 
     def filters

data/lib/rokaki/version.rb

@@ -1,3 +1,3 @@
 module Rokaki
-  VERSION = "0.12.0"
+  VERSION = "0.13.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rokaki
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Steve Martin
@@ -248,6 +248,7 @@ files:
 - ".rspec"
 - ".ruby-version"
 - ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - Guardfile