rokaki 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5dac3a2881b83e34f6e0ee5717c4103212b3c4606b0ca05420338544a56cdffd
-  data.tar.gz: 594b1e1ff90e0a86674ed06e0de962a3cf622814cc87f02317a1da4ddcceb437
+  metadata.gz: dcbf82920cbfeff8466f6ccd583f1a66652082e087c2d6641806be8720dd8d6c
+  data.tar.gz: 4165d387e1fba3820fc302ef414f0019077067a1dca7d307943030f0aec99207
 SHA512:
-  metadata.gz: 1246c456cd8c613d8288a5d6bc69c65eedd67545b854b2185f512b071a04e1341c9bffe9f86a713ab9106842a8b015a73b0f8f55e9d0fecf8741b47e824c015b
-  data.tar.gz: 2429fb0148ca0705edcf02bb434541968db87a7bda6cd26a0945d1ccec660b6a9ca45ff9f5798aeeedfd4f89371f3c1575f2d0f79d1914a695b4f898d35bf4b4
+  metadata.gz: 8e5d866b175e0799ad9bff2cbb8660e8ebca48785e508223e7583452eb7e95e56c1c35f15ff8625fc456365651b82efff40636579f90469d9909f650f6ee2b1d
+  data.tar.gz: e974f32a7626a94fb618295ea9600e9747af73bd35986f9e843a81b4bc6168c98180ef85d150fc1ad96ff4fa4700daae5d16d75596bc2d3dd9279ba8d6a98c64

data/.github/workflows/pages.yml

@@ -0,0 +1,31 @@
+name: Build documentation (no deploy)
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    env:
+      BUNDLE_GEMFILE: docs/Gemfile
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3.0'
+          bundler-cache: true
+
+      - name: Build site
+        run: |
+          bundle exec jekyll build -s docs -d _site
+
+      - name: Upload built site artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: site
+          path: _site

data/.github/workflows/spec.yml

@@ -25,8 +25,24 @@ jobs:
         - 5432:5432
         # needed because the postgres container does not provide a healthcheck
         options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
+
+      sqlserver:
+        image: mcr.microsoft.com/mssql/server:2022-latest
+        env:
+          ACCEPT_EULA: "Y"
+          MSSQL_SA_PASSWORD: "5QL5£rv£r"
+        ports:
+          - 1433:1433
+        # No built-in healthcheck; we'll wait in a step using nc
+
     steps:
       - uses: actions/checkout@v2
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y build-essential libpq-dev default-libmysqlclient-dev freetds-dev netcat-openbsd
+
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
@@ -34,6 +50,20 @@ jobs:
           ruby-version: 3.3.0
           # runs 'bundle install' and caches installed gems automatically
           bundler-cache: true
+
+      - name: Wait for databases to be ready
+        shell: bash
+        run: |
+          for i in {1..60}; do
+            nc -z 127.0.0.1 3306 && echo "MySQL up" && break || sleep 1
+          done
+          for i in {1..60}; do
+            nc -z 127.0.0.1 5432 && echo "Postgres up" && break || sleep 1
+          done
+          for i in {1..120}; do
+            nc -z 127.0.0.1 1433 && echo "SQL Server up" && break || sleep 1
+          done
+
       - name: Run tests
         run: |
           ./spec/ordered_run.sh

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rokaki (0.10.0)
+    rokaki (0.12.0)
       activesupport
 
 GEM
@@ -13,6 +13,9 @@ GEM
       activemodel (= 8.0.3)
       activesupport (= 8.0.3)
       timeout (>= 0.4.0)
+    activerecord-sqlserver-adapter (8.0.9)
+      activerecord (~> 8.0.0)
+      tiny_tds
     activesupport (8.0.3)
       base64
       benchmark (>= 0.3)
@@ -132,6 +135,16 @@ GEM
     sqlite3 (2.7.4-x86_64-linux-musl)
     thor (1.4.0)
     timeout (0.4.3)
+    tiny_tds (3.3.0)
+      bigdecimal (~> 3)
+    tiny_tds (3.3.0-aarch64-linux-gnu)
+      bigdecimal (~> 3)
+    tiny_tds (3.3.0-aarch64-linux-musl)
+      bigdecimal (~> 3)
+    tiny_tds (3.3.0-x86_64-linux-gnu)
+      bigdecimal (~> 3)
+    tiny_tds (3.3.0-x86_64-linux-musl)
+      bigdecimal (~> 3)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
     uri (1.0.3)
@@ -152,6 +165,7 @@ PLATFORMS
 
 DEPENDENCIES
   activerecord
+  activerecord-sqlserver-adapter
   bundler (~> 2.0)
   database_cleaner-active_record
   factory_bot
@@ -165,6 +179,7 @@ DEPENDENCIES
   rokaki!
   rspec (~> 3.0)
   sqlite3
+  tiny_tds
 
 BUNDLED WITH
    2.5.3

data/README.md

@@ -1,10 +1,15 @@
 # Rokaki
 
 [![Gem Version](https://badge.fury.io/rb/rokaki.svg)](https://badge.fury.io/rb/rokaki)
+[![Run RSpec tests](https://github.com/tevio/rokaki/actions/workflows/spec.yml/badge.svg)](https://github.com/tevio/rokaki/actions/workflows/spec.yml)
 
-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".
+This gem was written to dry up filtering services in ActiveRecord based Rails apps or any plain Ruby app looking to implement "filters" or "faceted" search.
 
-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`.
+The overall vision is to abstract away all of the lower level repetitive SQL and relational code to allow you to write model filters in a simple, relatively intuitive way, using ruby hashes and arrays mostly.
+
+The DSL allows you to construct complex search models to filter results through without writing any SQL. I would recommend the reader to consult the specs in order to understand the features and syntax in detail, an intermediate understanding of Ruby and rspec TDD, and basic relational logic are recommended.
+
+There are two modes of use, `Filterable` (designed for plain Ruby) and `FilterModel` (designed for Rails) 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:
@@ -137,7 +142,7 @@ You can specify several configuration options, for example a `filter_key_prefix`
 ## `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:-
+Include `Rokaki::FilterModel` in any ActiveRecord model (only AR >= 8.0.3 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
 # Given the models
@@ -173,7 +178,7 @@ You can also filter collections of fields, simply pass an array of filter values
 
 
 ### Partial matching
-You can use `like` (or, if you use postgres, the case insensitive `ilike`) to perform a partial match on a specific field, there are 3 options:- `:prefix`, `:circumfix` and `:suffix`. There are two syntaxes you can use for this:-
+You can use `like` or the case insensitive `ilike` to perform a partial match on a specific field, there are 3 options:- `:prefix`, `:circumfix` and `:suffix`. There are two syntaxes you can use for this:-
 
 #### 1. The `filter` command syntax
 
@@ -183,7 +188,7 @@ class ArticleFilter
   include Rokaki::FilterModel
 
   filter :article,
-    like: { # you can use ilike here instead if you use postgres and want case insensitive results
+    like: { # you can use ilike here instead if you want case insensitive results
       author: {
         first_name: :circumfix,
         last_name: :circumfix
@@ -323,7 +328,7 @@ class ArticleFilter
 
   filters :date, :title, author: [:first_name, :last_name]
   like title: :circumfix
-  # ilike title: :circumfix # case insensitive postgres mode
+  # ilike title: :circumfix # case insensitive mode
 
   attr_accessor :filters
 
@@ -436,7 +441,13 @@ docker pull mysql
 docker run --name rokaki-mysql -e MYSQL_ROOT_PASSWORD=rokaki -e MYSQL_PASSWORD=rokaki -e MYSQL_DATABASE=rokaki -e MYSQL_USER=rokaki -d -p 3306:3306 mysql:latest mysqld
 ```
 
-Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+### Specialised test runner
+The test suite is designed to run against all supported database backends, since this can cause problems with timing and connection pools, the recommended way to run the tests is via a shell script.
+
+From the rokaki root directory run: `./spec/ordered_run.sh`. This is the same script that runs on the Github CI here: [![Run RSpec tests](https://github.com/tevio/rokaki/actions/workflows/spec.yml/badge.svg)](https://github.com/tevio/rokaki/actions/workflows/spec.yml)
+
+### Standard test runner (only recommended for development cycles)
+You can still run `rake spec` to run the tests, there's no guarantee they will all pass due to race conditions from using multiple db backends (see above), but this mode is recommended for focusing on specific backends or tests during development (comment out what you don't want). You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 

data/docs/Gemfile

@@ -0,0 +1,17 @@
+# docs/Gemfile
+source "https://rubygems.org"
+
+# Static site generator
+gem "jekyll", "~> 4.4"
+
+# Theme used by docs/_config.yml
+gem "minima", "~> 2.5"
+
+# GitHub-flavored Markdown support
+gem "kramdown-parser-gfm", "~> 1.1"
+
+# Ruby 3+ local serving requires webrick
+gem "webrick", "~> 1.8"
+
+# Ensure compatibility with workflow expectation
+gem "rake", "~> 13.3"

data/docs/_config.yml

@@ -0,0 +1,26 @@
+title: Rokaki
+description: A DSL for filtering data in web requests (ActiveRecord)
+# For project pages (https://<user>.github.io/<repo>), set:
+#   url: "https://tevio.github.io"
+#   baseurl: "/rokaki"
+# This ensures theme assets like /assets/main.css resolve under /rokaki/ on GitHub Pages.
+baseurl: "/rokaki"
+url: "https://tevio.github.io"
+theme: minima
+
+# Build settings
+markdown: kramdown
+kramdown:
+  input: GFM
+
+# Exclude existing generated RDoc folder from site
+exclude:
+  - doc/
+  - pkg/
+  - spec/
+  - Gemfile
+  - Gemfile.lock
+  - Rakefile
+  - rokaki.gemspec
+  - Guardfile
+  - README.md

data/docs/adapters.md

@@ -0,0 +1,46 @@
+---
+layout: page
+title: Database adapters
+permalink: /adapters
+---
+
+Rokaki generates adapter‑aware SQL for PostgreSQL, MySQL, and SQL Server.
+
+## Overview
+
+- PostgreSQL
+  - Case‑insensitive: `ILIKE`
+  - Case‑sensitive: `LIKE`
+  - Multi‑term: `ANY (ARRAY[...])`
+- MySQL
+  - Case‑insensitive: `LIKE`
+  - Case‑sensitive: `LIKE BINARY`
+  - Nested‑like filters may use `REGEXP` where designed in the library
+- SQL Server
+  - Uses `LIKE` with safe escaping
+  - Multi‑term input expands to OR‑chained predicates (e.g., `(col LIKE :q0 OR col LIKE :q1 ...)`) with `ESCAPE '\\'`
+  - Case sensitivity follows DB collation by default; future versions may add inline `COLLATE` options
+
+## LIKE modes
+
+All adapters support the same modes, which you declare via the values in your `like` mapping (there is no `modes:` option):
+
+- `prefix` → `%term`
+- `suffix` → `term%`
+- `circumfix` → `%term%` (synonyms supported: `:parafix`, `:confix`, `:ambifix`)
+
+Example:
+
+```ruby
+# Declare modes via like-mapping values (no block DSL)
+like title: :circumfix
+like author: { first_name: :prefix }
+```
+
+When you pass an array of terms, Rokaki composes adapter‑appropriate SQL that matches any of the terms.
+
+## Notes on case sensitivity
+
+- PostgreSQL: `ILIKE` is case‑insensitive; `LIKE` is case‑sensitive depending on collation/LC settings but generally treated as case‑sensitive for ASCII.
+- MySQL: `LIKE` case sensitivity depends on column collation; `LIKE BINARY` forces byte comparison (case‑sensitive for ASCII).
+- SQL Server: The server/database/column collation determines sensitivity. Rokaki currently defers to your DB’s default. If you need deterministic behavior regardless of DB defaults, consider using a case‑sensitive collation on the column or open an issue to discuss inline `COLLATE` options.

data/docs/configuration.md

@@ -0,0 +1,63 @@
+---
+layout: page
+title: Configuration
+permalink: /configuration
+---
+
+This page covers configuration, environment overrides, and tips for running the test suite across adapters.
+
+## Environment variables
+
+Rokaki's test helpers (used in the specs) support environment variable overrides for all adapters. These are useful when your local databases run on non‑default ports or hosts.
+
+### SQL Server
+- `SQLSERVER_HOST` (default: `localhost`)
+- `SQLSERVER_PORT` (default: `1433`)
+- `SQLSERVER_USERNAME` (default: `sa`)
+- `SQLSERVER_PASSWORD`
+- `SQLSERVER_DATABASE` (default: `rokaki`)
+
+### MySQL
+- `MYSQL_HOST` (default: `127.0.0.1`)
+- `MYSQL_PORT` (default: `3306`)
+- `MYSQL_USERNAME` (default: `rokaki`)
+- `MYSQL_PASSWORD` (default: `rokaki`)
+- `MYSQL_DATABASE` (default: `rokaki`)
+
+### PostgreSQL
+- `POSTGRES_HOST` (default: `127.0.0.1`)
+- `POSTGRES_PORT` (default: `5432`)
+- `POSTGRES_USERNAME` (default: `postgres`)
+- `POSTGRES_PASSWORD` (default: `postgres`)
+- `POSTGRES_DATABASE` (default: `rokaki`)
+
+## SQL Server notes
+
+- Rokaki uses `LIKE` with proper escaping and OR expansion for arrays of terms.
+- Case sensitivity follows your database/column collation. Future versions may allow inline `COLLATE` options.
+
+## Running tests locally
+
+Ensure you have Ruby (see `.ruby-version`), then install dependencies and run specs.
+
+```bash
+bundle install
+./spec/ordered_run.sh
+```
+
+Or run a single adapter suite, for example SQL Server:
+
+```bash
+bundle exec rspec spec/lib/03_sqlserver_aware_spec.rb
+```
+
+If your SQL Server listens on a different port (e.g., 1434), set an override:
+
+```bash
+export SQLSERVER_PORT=1434
+bundle exec rspec spec/lib/03_sqlserver_aware_spec.rb
+```
+
+## GitHub Actions
+
+The repository includes CI that starts MySQL (9.4), PostgreSQL (13), and SQL Server (2022) services and runs the ordered spec suite. See `.github/workflows/spec.yml`.

data/docs/index.md

@@ -0,0 +1,75 @@
+---
+layout: home
+title: Rokaki
+permalink: /
+---
+
+Rokaki is a small Ruby library that helps you build safe, composable filters for ActiveRecord queries in web requests.
+
+- Works with PostgreSQL, MySQL, and SQL Server
+- Supports simple and nested filters
+- LIKE-based matching with prefix/suffix/circumfix modes (circumfix also accepts synonyms: parafix, confix, ambifix)
+- Array-of-terms matching (adapter-aware)
+
+Get started below or jump to:
+- [Usage](./usage)
+- [Database adapters](./adapters)
+- [Configuration](./configuration)
+
+## Installation
+
+Add to your application's Gemfile:
+
+```ruby
+gem "rokaki", "~> 0.11"
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+## Quick start
+
+Use `Rokaki::FilterModel` and declare mappings with method arguments (no block DSL).
+
+```ruby
+class ArticleQuery
+  include Rokaki::FilterModel
+
+  # Tell Rokaki which model to query and which DB adapter semantics to use
+  filter_model :article, db: :postgres # or :mysql, :sqlserver
+
+  # Map a single query key (:q) to multiple LIKE targets on Article
+  define_query_key :q
+  like title: :circumfix, content: :circumfix
+
+  # Nested LIKEs on associated models are expressed with hashes
+  like author: { first_name: :prefix, last_name: :suffix }
+
+  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
+
+- prefix: matches values that start with given term(s)
+- suffix: matches values that end with given term(s)
+- circumfix: matches values that contain given term(s)
+
+All modes accept either a single string or an array of terms.
+
+## Next steps
+
+- Learn the full DSL and examples in [Usage](./usage)
+- See adapter specifics (PostgreSQL/MySQL/SQL Server) in [Database adapters](./adapters)
+- Configure connections and environment variables in [Configuration](./configuration)

data/docs/usage.md

@@ -0,0 +1,100 @@
+---
+layout: page
+title: Usage
+permalink: /usage
+---
+
+This page shows how to use Rokaki to define filters and apply them to ActiveRecord relations.
+
+## Installation
+
+Add the gem to your Gemfile and bundle:
+
+```ruby
+gem "rokaki", "~> 0.11"
+```
+
+```bash
+bundle install
+```
+
+## Basic setup
+
+Include `Rokaki::Filterable` in models you want to filter, and define a `filter_map` with fields and nested associations.
+
+```ruby
+class Author < ActiveRecord::Base
+  has_many :articles
+end
+
+class ArticleQuery
+  include Rokaki::FilterModel
+  belongs_to :author
+
+  # Choose model and adapter
+  filter_model :article, db: :postgres # or :mysql, :sqlserver
+
+  # Map a single query key (:q) to multiple LIKE targets
+  define_query_key :q
+  like title: :circumfix, content: :circumfix
+
+  # Nested LIKEs via hash mapping (no block DSL)
+  like author: { first_name: :prefix, last_name: :suffix }
+end
+```
+
+## Applying filters
+
+Call `Model.filter(params)` to build a relation based on supported keys.
+
+```ruby
+params = {
+  title_prefix: "Intro",
+  q: ["ruby", "rails"],
+  author_last_name: "martin"
+}
+
+filtered = Article.filter(params)
+# => ActiveRecord::Relation (chainable)
+```
+
+You can keep chaining other scopes/clauses:
+
+```ruby
+Article.filter(params).order(published: :desc).limit(20)
+```
+
+## LIKE modes and affix options
+
+Declare the LIKE mode via the value in your `like` mapping (there is no `modes:` option). For example: `like title: :prefix`.
+
+- `prefix` → matches strings that start with a term (pattern: `%term`)
+- `suffix` → matches strings that end with a term (pattern: `term%`)
+- `circumfix` → matches strings that contain a term (pattern: `%term%`)
+  - Synonyms supported: `:parafix`, `:confix`, `:ambifix` (all behave the same as `:circumfix`)
+
+Each accepts a single string or an array of strings. Rokaki generates adapter‑aware SQL:
+
+- PostgreSQL: `LIKE`/`ILIKE` with `ANY (ARRAY[...])`
+- MySQL: `LIKE`/`LIKE BINARY` and, in nested-like contexts, `REGEXP` where designed
+- SQL Server: `LIKE` with safe escaping; arrays expand into OR chains of parameterized `LIKE` predicates
+
+## Nested filters
+
+Use `nested :association` to scope filters to joined tables. Rokaki handles the necessary joins and qualified columns.
+
+```ruby
+filter_map do
+  nested :author do
+    like :first_name, key: :author_first
+  end
+end
+```
+
+Params would include `author_first`, `author_first_prefix`, etc.
+
+## Customization tips
+
+- 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`).

data/lib/rokaki/filter_model/basic_filter.rb

@@ -38,6 +38,10 @@ module Rokaki
           'LIKE'
         elsif db == :mysql
           'LIKE BINARY'
+        elsif db == :sqlserver
+          'LIKE'
+        else
+          'LIKE'
         end
       end
 
@@ -46,6 +50,10 @@ module Rokaki
           'ILIKE'
         elsif db == :mysql
           'LIKE'
+        elsif db == :sqlserver
+          'LIKE'
+        else
+          'LIKE'
         end
       end
 
@@ -94,6 +102,9 @@ module Rokaki
         if db == :postgres
           query = "@model.where(\"#{key} #{type} ANY (ARRAY[?])\", "
           query += "prepare_terms(#{filter}, :#{mode}))"
+        elsif db == :sqlserver
+          # Delegate to helper that supports arrays and escaping with ESCAPE
+          query = "sqlserver_like(@model, \"#{key}\", \"#{type}\", #{filter}, :#{mode})"
         else
           query = "@model.where(\"#{key} #{type} :query\", "
           query += "query: \"%\#{#{filter}}%\")" if mode == :circumfix

data/lib/rokaki/filter_model/nested_filter.rb

@@ -70,6 +70,10 @@ module Rokaki
           'LIKE'
         elsif db == :mysql
           'LIKE BINARY'
+        elsif db == :sqlserver
+          'LIKE'
+        else
+          'LIKE'
         end
       end
 
@@ -78,6 +82,10 @@ module Rokaki
           'ILIKE'
         elsif db == :mysql
           'LIKE'
+        elsif db == :sqlserver
+          'LIKE'
+        else
+          'LIKE'
         end
       end
 
@@ -131,19 +139,27 @@ module Rokaki
         where = where.join
 
         if search_mode
-          query = build_like_query(
-            type: type,
-            query: '',
-            filter: "#{prefix}#{name}",
-            search_mode: search_mode,
-            key: keys.last.to_s.pluralize,
-            leaf: leaf
-          )
+          if db == :sqlserver
+            key_leaf = "#{keys.last.to_s.pluralize}.#{leaf}"
+            @filter_methods << "def #{prefix}filter#{infix}#{name};"\
+              "sqlserver_like(@model.joins(#{joins}), \"#{key_leaf}\", \"#{type}\", #{prefix}#{name}, :#{search_mode}); end;"
 
-          @filter_methods << "def #{prefix}filter#{infix}#{name};"\
-            "@model.joins(#{joins}).#{query}; end;"
-
-          @filter_templates << "@model = #{prefix}filter#{infix}#{name} if #{prefix}#{name};"
+            @filter_templates << "@model = #{prefix}filter#{infix}#{name} if #{prefix}#{name};"
+          else
+            query = build_like_query(
+              type: type,
+              query: '',
+              filter: "#{prefix}#{name}",
+              search_mode: search_mode,
+              key: keys.last.to_s.pluralize,
+              leaf: leaf
+            )
+
+            @filter_methods << "def #{prefix}filter#{infix}#{name};"\
+              "@model.joins(#{joins}).#{query}; end;"
+
+            @filter_templates << "@model = #{prefix}filter#{infix}#{name} if #{prefix}#{name};"
+          end
         else
           @filter_methods << "def #{prefix}filter#{infix}#{name};"\
             "@model.joins(#{joins}).where(#{where}); end;"

data/lib/rokaki/filter_model/nested_like_filters.rb

@@ -194,22 +194,37 @@ module Rokaki
         leaf = nil
         leaf = keys.pop
 
+        # Compute key_leaf (qualified column) like other branches
+        key_leaf = keys.last ? "#{keys.last.to_s.pluralize}.#{leaf}" : leaf
+
+        if db == :sqlserver
+          # Build relation base with joins
+          if join_map.empty?
+            rel_expr = "@model"
+          elsif join_map.is_a?(Array)
+            rel_expr = "@model.joins(*#{join_map})"
+          else
+            rel_expr = "@model.joins(**#{join_map})"
+          end
 
-        query = build_like_query(
-          type: type,
-          query: '',
-          filter: filter_name,
-          search_mode: search_mode,
-          key: keys.last,
-          leaf: leaf
-        )
-
-        if join_map.empty?
-          filter_query = "@model.#{query}"
-        elsif join_map.is_a?(Array)
-          filter_query = "@model.joins(*#{join_map}).#{query}"
+          filter_query = "sqlserver_like(#{rel_expr}, \"#{key_leaf}\", \"#{type.to_s.upcase}\", #{filter_name}, :#{search_mode})"
         else
-          filter_query = "@model.joins(**#{join_map}).#{query}"
+          query = build_like_query(
+            type: type,
+            query: '',
+            filter: filter_name,
+            search_mode: search_mode,
+            key: keys.last,
+            leaf: leaf
+          )
+
+          if join_map.empty?
+            filter_query = "@model.#{query}"
+          elsif join_map.is_a?(Array)
+            filter_query = "@model.joins(*#{join_map}).#{query}"
+          else
+            filter_query = "@model.joins(**#{join_map}).#{query}"
+          end
         end
 
         if mode == or_key
@@ -225,9 +240,20 @@ module Rokaki
         if db == :postgres
           query = "where(\"#{key_leaf} #{type.to_s.upcase} ANY (ARRAY[?])\", "
           query += "prepare_terms(#{filter}, :#{search_mode}))"
-        else
+        elsif db == :mysql
           query = "where(\"#{key_leaf} #{type.to_s.upcase} :query\", "
           query += "query: prepare_regex_terms(#{filter}, :#{search_mode}))"
+        else # :sqlserver and others
+          query = "where(\"#{key_leaf} #{type.to_s.upcase} :query\", "
+          if search_mode == :circumfix
+            query += "query: \"%\#{#{filter}}%\")"
+          elsif search_mode == :prefix
+            query += "query: \"%\#{#{filter}}\")"
+          elsif search_mode == :suffix
+            query += "query: \"\#{#{filter}}%\")"
+          else
+            query += "query: \"%\#{#{filter}}%\")"
+          end
         end
 
         query

data/lib/rokaki/filter_model.rb

@@ -19,6 +19,56 @@ module Rokaki
       end
     end
 
+    # Escape special LIKE characters in SQL Server patterns: %, _, [ and \\
+    def escape_like(term)
+      term.to_s.gsub(/[\\%_\[]/) { |m| "\\#{m}" }
+    end
+
+    # Build LIKE patterns with proper prefix/suffix/circumfix and escaping for SQL Server
+    # Returns a String when param is scalar, or an Array of Strings when param is an Array
+    def prepare_like_terms(param, mode)
+      if Array === param
+        case mode
+        when :circumfix
+          param.map { |t| "%#{escape_like(t)}%" }
+        when :prefix
+          param.map { |t| "%#{escape_like(t)}" }
+        when :suffix
+          param.map { |t| "#{escape_like(t)}%" }
+        else
+          param.map { |t| "%#{escape_like(t)}%" }
+        end
+      else
+        case mode
+        when :circumfix
+          "%#{escape_like(param)}%"
+        when :prefix
+          "%#{escape_like(param)}"
+        when :suffix
+          "#{escape_like(param)}%"
+        else
+          "%#{escape_like(param)}%"
+        end
+      end
+    end
+
+    # Compose a SQL Server LIKE relation supporting arrays of terms (OR chained)
+    # column should be a fully qualified column expression, e.g., "authors.first_name" or "cs.title"
+    # type is usually "LIKE"
+    def sqlserver_like(model, column, type, value, mode)
+      terms = prepare_like_terms(value, mode)
+      if terms.is_a?(Array)
+        return model.none if terms.empty?
+        rel = model.where("#{column} #{type} :q0 ESCAPE '\\'", q0: terms[0])
+        terms[1..-1]&.each_with_index do |t, i|
+          rel = rel.or(model.where("#{column} #{type} :q#{i + 1} ESCAPE '\\'", "q#{i + 1}".to_sym => t))
+        end
+        rel
+      else
+        model.where("#{column} #{type} :q ESCAPE '\\'", q: terms)
+      end
+    end
+
     def prepare_regex_terms(param, mode)
       if Array === param
         param_map = param.map { |term| ".*#{term}.*" } if mode == :circumfix
@@ -53,6 +103,23 @@ module Rokaki
 
       private
 
+      def normalize_like_modes(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) do |(k, v), h|
+            h[k] = normalize_like_modes(v)
+          end
+        when Array
+          obj.map { |e| normalize_like_modes(e) }
+        when Symbol
+          # Treat alternative affixes as circumfix
+          return :circumfix if [:parafix, :confix, :ambifix].include?(obj)
+          obj
+        else
+          obj
+        end
+      end
+
       def filter_map(model, query_key, options)
         filter_model(model)
         @filter_map_query_key = query_key
@@ -187,6 +254,10 @@ module Rokaki
         elsif @_filter_db == :mysql
           # 'LIKE BINARY'
           'REGEXP'
+        elsif @_filter_db == :sqlserver
+          'LIKE'
+        else
+          'LIKE'
         end
       end
 
@@ -196,22 +267,28 @@ module Rokaki
         elsif @_filter_db == :mysql
           # 'LIKE'
           'REGEXP'
+        elsif @_filter_db == :sqlserver
+          'LIKE'
+        else
+          'LIKE'
         end
       end
 
       def like(args)
         raise ArgumentError, 'argument mush be a hash' unless args.is_a? Hash
-        @_like_semantics = (@_like_semantics || {}).merge(args)
+        normalized = normalize_like_modes(args)
+        @_like_semantics = (@_like_semantics || {}).merge(normalized)
 
-        like_keys = LikeKeys.new(args)
+        like_keys = LikeKeys.new(normalized)
         like_filters(like_keys, term_type: case_sensitive)
       end
 
       def ilike(args)
         raise ArgumentError, 'argument mush be a hash' unless args.is_a? Hash
-        @i_like_semantics = (@i_like_semantics || {}).merge(args)
+        normalized = normalize_like_modes(args)
+        @i_like_semantics = (@i_like_semantics || {}).merge(normalized)
 
-        like_keys = LikeKeys.new(args)
+        like_keys = LikeKeys.new(normalized)
         like_filters(like_keys, term_type: case_insensitive)
       end
 

data/lib/rokaki/version.rb

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

data/rokaki.gemspec

@@ -47,5 +47,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'mysql2'
   spec.add_development_dependency 'sqlite3'
   spec.add_development_dependency 'database_cleaner-active_record'
+  # For SQL Server testing
+  spec.add_development_dependency 'tiny_tds'
+  spec.add_development_dependency 'activerecord-sqlserver-adapter'
 
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rokaki
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Steve Martin
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-02 00:00:00.000000000 Z
+date: 2025-10-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -206,6 +206,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: tiny_tds
+  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: activerecord-sqlserver-adapter
+  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
@@ -214,12 +242,12 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/workflows/codeql-analysis.yml"
+- ".github/workflows/pages.yml"
 - ".github/workflows/spec.yml"
 - ".gitignore"
 - ".rspec"
 - ".ruby-version"
 - ".travis.yml"
-- CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock
 - Guardfile
@@ -228,6 +256,12 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- docs/Gemfile
+- docs/_config.yml
+- docs/adapters.md
+- docs/configuration.md
+- docs/index.md
+- docs/usage.md
 - lib/rokaki.rb
 - lib/rokaki/filter_model.rb
 - lib/rokaki/filter_model/basic_filter.rb

data/CODE_OF_CONDUCT.md

@@ -1,74 +0,0 @@
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-In the interest of fostering an open and welcoming environment, we as
-contributors and maintainers pledge to making participation in our project and
-our community a harassment-free experience for everyone, regardless of age, body
-size, disability, ethnicity, gender identity and expression, level of experience,
-nationality, personal appearance, race, religion, or sexual identity and
-orientation.
-
-## Our Standards
-
-Examples of behavior that contributes to creating a positive environment
-include:
-
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
-
-Examples of unacceptable behavior by participants include:
-
-* The use of sexualized language or imagery and unwelcome sexual attention or
-advances
-* Trolling, insulting/derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or electronic
-  address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
-  professional setting
-
-## Our Responsibilities
-
-Project maintainers are responsible for clarifying the standards of acceptable
-behavior and are expected to take appropriate and fair corrective action in
-response to any instances of unacceptable behavior.
-
-Project maintainers have the right and responsibility to remove, edit, or
-reject comments, commits, code, wiki edits, issues, and other contributions
-that are not aligned to this Code of Conduct, or to ban temporarily or
-permanently any contributor for other behaviors that they deem inappropriate,
-threatening, offensive, or harmful.
-
-## Scope
-
-This Code of Conduct applies both within project spaces and in public spaces
-when an individual is representing the project or its community. Examples of
-representing a project or community include using an official project e-mail
-address, posting via an official social media account, or acting as an appointed
-representative at an online or offline event. Representation of a project may be
-further defined and clarified by project maintainers.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at steve@martian.media. All
-complaints will be reviewed and investigated and will result in a response that
-is deemed necessary and appropriate to the circumstances. The project team is
-obligated to maintain confidentiality with regard to the reporter of an incident.
-Further details of specific enforcement policies may be posted separately.
-
-Project maintainers who do not follow or enforce the Code of Conduct in good
-faith may face temporary or permanent repercussions as determined by other
-members of the project's leadership.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
-available at [http://contributor-covenant.org/version/1/4][version]
-
-[homepage]: http://contributor-covenant.org
-[version]: http://contributor-covenant.org/version/1/4/