rokaki 0.17.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52ffc6e9a926824c6730632c566d42570997aa5e2a2674ea07e79d0722a628fc
-  data.tar.gz: 248ecf8294fe48488f0b8a8990f1602ab7cd3c10af95731be2a8e3f0933905c8
+  metadata.gz: 1c59d25915c0eda9030515a3b92835664ab91951cc51faf13be126bbc0f6053c
+  data.tar.gz: 38e490b4dc7cbe7a1303d03af2f5fa7f41f8100ac4b5787f36b9b3e2d1cf8648
 SHA512:
-  metadata.gz: ff1071aaa8e6a151fa0382ec294df042a4afb5d8c8e00bd5a25fe2ffdc67ba54971b649edc5cfd3019895a44c64ee2b0ce352032f8f24d2a525a3cd2ef6dadd0
-  data.tar.gz: 99dcd53ddb3c068522a7a2eba6b262c8f5bfb9bc78433596e4d15a8ea1363e31895be3b2c39270276955a802fe2198ae2d74ddba4d60a063519903ace4f71263
+  metadata.gz: 70819c707de3dfdc0228d238d7b750c48ddba7b6fc23b8f74746ddae1421e88c4dbd5be75a620473af32ae82852aaf4de90eb26927d0efd9ee97b6ecc2588281
+  data.tar.gz: 7c020e3c58a55c65329c25f6503c2669a7ff08f1e86fedde551b8e38a6ba2f3b50042daea0db255ca0adb27bd6e1d19f59bb8f9fe6a250c196d8dbd54634b387

data/CHANGELOG.md

@@ -1,6 +1,13 @@
 ### Unreleased
 - (no changes yet)
 
+### 0.18.0 — 2025-10-28
+- Feature: inequality and nullability operators at leaf level across all adapters:
+  - `neq`, `not_in`, `is_null`, `is_not_null`, `gt`, `gte`, `lt`, `lte`
+- Tests: shared examples added and wired into all adapter-aware suites; full matrix passing.
+- Docs: usage and DSL syntax updated; adapters page notes portability of these operators.
+- Chore: bump version to 0.18.0 and update install snippets to `~> 0.18`.
+
 ### 0.17.0 — 2025-10-28
 - Version bump to 0.17.0.
 - Documentation: Updated installation snippets to `~> 0.17`.

data/Gemfile.lock

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

data/docs/_config.yml

@@ -8,6 +8,14 @@ baseurl: "/rokaki"
 url: "https://tevio.github.io"
 theme: minima
 
+# Limit header navigation to these pages to avoid top-level Oracle link
+header_pages:
+  - index.md
+  - usage.md
+  - dsl_syntax.md
+  - adapters.md
+  - configuration.md
+
 # Build settings
 markdown: kramdown
 kramdown:

data/docs/adapters.md

@@ -22,7 +22,7 @@ Rokaki generates adapter‑aware SQL for PostgreSQL, MySQL, SQL Server, Oracle,
   - Case sensitivity follows DB collation by default; future versions may add inline `COLLATE` options
 - Oracle
   - Uses `LIKE`; arrays of terms are OR‑chained; case‑insensitive paths use `UPPER(column) LIKE UPPER(:q)`
-  - See the dedicated page: [Oracle connections](/adapters/oracle) for connection strings, NLS settings, and common errors.
+  - See the dedicated page: [Oracle connections](/rokaki/adapters/oracle) for connection strings, NLS settings, and common errors.
 - SQLite
   - Embedded (no separate server needed)
   - Uses `LIKE`; arrays of terms are OR‑chained across predicates
@@ -81,6 +81,10 @@ database: ":memory:"
 To persist a database file locally, set `SQLITE_DATABASE` to a path (e.g., `tmp/test.sqlite3`).
 
 
+## Inequality and null filters
+
+The following leaf-level operators are adapter-agnostic across PostgreSQL, MySQL, SQL Server, Oracle, and SQLite: `neq`, `not_in`, `is_null`, `is_not_null`, `gt`, `gte`, `lt`, `lte`. Rokaki composes standard SQL (`<>`, `NOT IN`, `IS NULL`/`IS NOT NULL`, `>`, `>=`, `<`, `<=`) with bound parameters.
+
 ## Range/BETWEEN filters
 
 Rokaki’s range filters (`between`, lower-bound aliases like `from`/`min`, and upper-bound aliases like `to`/`max`) are adapter‑agnostic. The library always generates parameterized predicates using `BETWEEN`, `>=`, and `<=` on the target column.

data/docs/dsl_syntax.md

@@ -106,6 +106,14 @@ At a leaf field (e.g., `published` or `reviews.published`):
     - `{ published: { min: t1 } }` → `published >= t1`
     - `{ published: { max: t2 } }` → `published <= t2`
 
+- Operator-hash (inequality/null) → non-equality predicates
+  - Keys: `neq`, `not_in`, `is_null`, `is_not_null`, `gt`, `gte`, `lt`, `lte`
+  - Examples:
+    - `{ title: { neq: "Draft" } }` → `title <> 'Draft'`
+    - `{ title: { not_in: ["Draft", "Archived"] } }` → `title NOT IN (...)`
+    - `{ content: { is_null: true } }` → `content IS NULL`
+    - `{ published: { gt: t1, lte: t2 } }` → `published > t1 AND published <= t2`
+
 Notes:
 - Only the leaf level interprets these reserved keys. Join-structure keys do not carry operators.
 - Arrays never imply range; to express a range with an array, use `{ published: { between: [from, to] } }`.

data/docs/index.md

@@ -23,7 +23,7 @@ Get started below or jump to:
 Add to your application's Gemfile:
 
 ```ruby
-gem "rokaki", "~> 0.17"
+gem "rokaki", "~> 0.18"
 ```
 
 Then:
@@ -103,13 +103,13 @@ 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
+## What’s new in 0.17.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
+- Range filters as first-class filters (non-aggregates): `between`, lower bounds (`from`/`since`/`after`/`start`/`min`), upper bounds (`to`/`until`/`before`/`end`/`max`) on top-level and nested fields.
+- Arrays always mean equality `IN` lists; use a `Range` or `{ between: [from, to] }` to express ranges.
+- Block-form DSL parity across `FilterModel` and `Filterable`, with nested declarations for associations and leaves.
+- Backend auto-detection: adapter inferred from the model connection; pass `db:` only for multi-adapter apps or overrides.
+- Oracle documentation moved under Adapters: see [Database adapters](./adapters) → [Oracle connections](/adapters/oracle).
 
 ## Next steps
 

data/docs/usage.md

@@ -12,7 +12,7 @@ For a formal description of the mapping DSL and how payloads are interpreted (jo
 Add the gem to your Gemfile and bundle:
 
 ```ruby
-gem "rokaki", "~> 0.17"
+gem "rokaki", "~> 0.18"
 ```
 
 ```bash
@@ -123,8 +123,10 @@ Article.filter(published: { since: Date.new(2024,1,1), until: Date.new(2024,6,30
 Article.filter(published: { min: Date.new(2024,1,1) })   # >= 2024-01-01
 Article.filter(published: { max: Date.new(2024,12,31) }) # <= 2024-12-31
 
-# Between with a two-element Array
-Article.filter(published: [Date.new(2024,5,1), Date.new(2024,12,1)])
+# Arrays are equality lists (IN), not ranges
+# Use a Range or `{ between: [...] }` for range filtering
+Article.filter(published: [Date.new(2024,5,1), Date.new(2024,12,1)]) # => IN (equality list)
+Article.filter(published: { between: [Date.new(2024,5,1), Date.new(2024,12,1)] })
 ```
 
 Nested fields use the same sub-keys and value shapes:
@@ -153,7 +155,7 @@ Article.filter(reviews_published: (Time.utc(2024,1,1)..Time.utc(2024,6,30)))
 
 Behavior notes:
 - `min`/`max` are interpreted as lower/upper bounds, not aggregate functions.
-- Passing a `Range` or two-element `Array` directly as the field value is treated as a between filter automatically.
+- Passing a `Range` directly as the field value is treated as a between filter automatically. Two-element `Array`s are not ranges unless wrapped with `{ between: [...] }`.
 - Arrays with more than two elements are treated as equality lists (`IN (?)`) — use `{ between: [...] }` if you intend a range.
 - `nil` bounds are ignored: only the provided side is applied (e.g., `{ from: t }` becomes `>= t`).
 - All generated predicates are parameterized and adapter‑agnostic (`BETWEEN`, `>=`, `<=`).
@@ -385,3 +387,33 @@ Notes:
 - This approach is production‑ready and requires no core changes to Rokaki.
 - You can cache the generated class by a digest of the payload to avoid recompiling.
 - For maximum safety, validate/allow‑list models/columns coming from untrusted payloads.
+
+
+
+## Inequality and null filters
+
+Use leaf-level sub-keys to express non-equality predicates on top-level or nested fields.
+
+- Not equal: `{ field: { neq: value } }` → `<>`
+- Not in: `{ field: { not_in: [v1, v2] } }` → `NOT IN (...)`
+- Nullability:
+  - `{ field: { is_null: true } }` → `IS NULL`
+  - `{ field: { is_not_null: true } }` (or `{ is_null: false }`) → `IS NOT NULL`
+- Explicit comparisons: `{ field: { gt: x, gte: x, lt: x, lte: x } }`
+
+Examples:
+```ruby
+# Top-level
+Article.filter(title:   { neq: "Draft" })
+Article.filter(title:   { not_in: ["Draft", "Archived"] })
+Article.filter(content: { is_null: true })
+Article.filter(published: { gt: Time.utc(2024,1,1) })
+
+# Nested
+Article.filter(author: { first_name: { neq: "Ada" } })
+Article.filter(reviews: { published: { lte: Time.utc(2024,6,1,12) } })
+```
+
+Notes:
+- Arrays remain equality `IN` lists unless used under `not_in`.
+- These predicates are adapter-agnostic and work the same across PostgreSQL, MySQL, SQL Server, Oracle, and SQLite.

data/lib/rokaki/filter_model/basic_filter.rb

@@ -120,8 +120,38 @@ module Rokaki
                 elsif !_to.nil?
                   @model.where("#{key} <= :to", to: _to)
                 else
-                  # Fall back to equality with the original hash
-                  @model.where(#{key}: _val)
+                  # Inequality/nullability operators
+                  _op_neq         = _val[:neq] || _val['neq']
+                  _op_not_in      = _val[:not_in] || _val['not_in']
+                  _op_is_null     = _val[:is_null] || _val['is_null']
+                  _op_is_not_null = _val[:is_not_null] || _val['is_not_null']
+                  _op_gt          = _val[:gt] || _val['gt']
+                  _op_gte         = _val[:gte] || _val['gte']
+                  _op_lt          = _val[:lt] || _val['lt']
+                  _op_lte         = _val[:lte] || _val['lte']
+
+                  if !_op_neq.nil?
+                    @model.where("#{key} <> :v", v: _op_neq)
+                  elsif _op_not_in
+                    _arr = Array(_op_not_in)
+                    return @model.none if _arr.empty?
+                    @model.where("#{key} NOT IN (?)", _arr)
+                  elsif _op_is_null == true
+                    @model.where("#{key} IS NULL")
+                  elsif _op_is_not_null == true || _op_is_null == false
+                    @model.where("#{key} IS NOT NULL")
+                  elsif !_op_gt.nil?
+                    @model.where("#{key} > :v", v: _op_gt)
+                  elsif !_op_gte.nil?
+                    @model.where("#{key} >= :v", v: _op_gte)
+                  elsif !_op_lt.nil?
+                    @model.where("#{key} < :v", v: _op_lt)
+                  elsif !_op_lte.nil?
+                    @model.where("#{key} <= :v", v: _op_lte)
+                  else
+                    # Fall back to equality with the original hash
+                    @model.where(#{key}: _val)
+                  end
                 end
               elsif _val.is_a?(Range)
                 #{build_between_query(filter: filter, key: key)}

data/lib/rokaki/filter_model/nested_filter.rb

@@ -185,7 +185,37 @@ module Rokaki
                 elsif !_to.nil?
                   rel.where("#{qualified_col} <= :to", to: _to)
                 else
-                  rel.where("#{qualified_col} = :v", v: _val)
+                  # Inequality/nullability operators
+                  _op_neq         = _val[:neq] || _val['neq']
+                  _op_not_in      = _val[:not_in] || _val['not_in']
+                  _op_is_null     = _val[:is_null] || _val['is_null']
+                  _op_is_not_null = _val[:is_not_null] || _val['is_not_null']
+                  _op_gt          = _val[:gt] || _val['gt']
+                  _op_gte         = _val[:gte] || _val['gte']
+                  _op_lt          = _val[:lt] || _val['lt']
+                  _op_lte         = _val[:lte] || _val['lte']
+
+                  if !_op_neq.nil?
+                    rel.where("#{qualified_col} <> :v", v: _op_neq)
+                  elsif _op_not_in
+                    _arr = Array(_op_not_in)
+                    return rel.none if _arr.empty?
+                    rel.where("#{qualified_col} NOT IN (?)", _arr)
+                  elsif _op_is_null == true
+                    rel.where("#{qualified_col} IS NULL")
+                  elsif _op_is_not_null == true || _op_is_null == false
+                    rel.where("#{qualified_col} IS NOT NULL")
+                  elsif !_op_gt.nil?
+                    rel.where("#{qualified_col} > :v", v: _op_gt)
+                  elsif !_op_gte.nil?
+                    rel.where("#{qualified_col} >= :v", v: _op_gte)
+                  elsif !_op_lt.nil?
+                    rel.where("#{qualified_col} < :v", v: _op_lt)
+                  elsif !_op_lte.nil?
+                    rel.where("#{qualified_col} <= :v", v: _op_lte)
+                  else
+                    rel.where("#{qualified_col} = :v", v: _val)
+                  end
                 end
               elsif _val.is_a?(Range)
                 rel.where("#{qualified_col} BETWEEN :from AND :to", from: _val.begin, to: _val.end)

data/lib/rokaki/version.rb

@@ -1,3 +1,3 @@
 module Rokaki
-  VERSION = "0.17.0"
+  VERSION = "0.18.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rokaki
 version: !ruby/object:Gem::Version
-  version: 0.17.0
+  version: 0.18.0
 platform: ruby
 authors:
 - Steve Martin