rokaki 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8fb8c022307112af51183df513130d6ad467142320a4db9be178870583c2394
-  data.tar.gz: 611539f7d9500f30c5a847a89a7548119c14d4eac47761e9c08b5e706ae9f77c
+  metadata.gz: dcbf82920cbfeff8466f6ccd583f1a66652082e087c2d6641806be8720dd8d6c
+  data.tar.gz: 4165d387e1fba3820fc302ef414f0019077067a1dca7d307943030f0aec99207
 SHA512:
-  metadata.gz: 3648caca4052f03440da996d1aed083c3ba9a29a5f14f06e9e9b2757d4d95f3356e793e22f1b1ebe0a149536a001367e6006d26d8521ce518885e32c36502130
-  data.tar.gz: ca064a797447597677bd5b2d2e00f6a2836bc5e69341990ac7da0742ccdc41383834f7a8c9bb6c4089a37e0293786c2536727b5c79d1dabf05a4c9df20f02b77
+  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/Gemfile.lock

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

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.rb

@@ -103,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
@@ -259,17 +276,19 @@ module Rokaki
 
       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.11.0"
+  VERSION = "0.12.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rokaki
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Steve Martin
@@ -242,6 +242,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/workflows/codeql-analysis.yml"
+- ".github/workflows/pages.yml"
 - ".github/workflows/spec.yml"
 - ".gitignore"
 - ".rspec"
@@ -255,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