dexkit 0.3.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec8b561633fbdf9989f8bc2476fe84ad2cd0c32177990d03380d63f59a8368a9
-  data.tar.gz: a348e6b1090374bfda6281e6a58fe16af3e285bb009fad38be60a3ba2c510720
+  metadata.gz: c6f6f437fc7f7726b58232820e6f1afd65c5adf674f51c4be07944a43d92a58b
+  data.tar.gz: 13046423e606ff6e000b6d557ce468efa94d0f13d8aa36530dc5ae69a688e097
 SHA512:
-  metadata.gz: 49d44b87657f65927b88c7fc1296ccab5d5246637a1887a126b0949e11bd452ecc0deb5fea90ef7f3329051b7bc13895f8f0ef73286705de44f7d21dccc0802a
-  data.tar.gz: 43182a4b6b6c904afe87fb385cff3a42057975363b5fd53e10744264f3af8cd5d48306b0ade26fd195b0d4fca696cbd85ac6c06e4434f48c280fb42a959beb80
+  metadata.gz: d48748c521d0e0c298ab78230797f7a22e45ae194fee6669f0f99669ea0ac1333b59158a8068211319694cbd073660f298babdb0a784b251444b579b898ba1c0
+  data.tar.gz: 4a574717aa7d2f5f5de9d192b86d7a6151d5b1a8cd2bba04c79e933cb2768e5c4d7cd05d91e22cf3ca9973cfca59467cd1a6972df8626ce90971ca9fec2a365d

data/README.md

@@ -18,7 +18,12 @@ class CreateUser < Dex::Operation
 
   def perform
     error!(:email_taken) if User.exists?(email: email)
-    User.create!(name: name, email: email)
+
+    user = User.create!(name: name, email: email)
+
+    after_commit { WelcomeMailer.with(user: user).deliver_later }
+
+    user
   end
 end
 
@@ -196,6 +201,49 @@ def save
 end
 ```
 
+## Queries
+
+Declarative query objects for filtering and sorting ActiveRecord relations.
+
+```ruby
+class UserSearch < Dex::Query
+  scope { User.all }
+
+  prop? :name,   String
+  prop? :role,   _Array(String)
+  prop? :age_min, Integer
+
+  filter :name,    :contains
+  filter :role,    :in
+  filter :age_min, :gte, column: :age
+
+  sort :name, :created_at, default: "-created_at"
+end
+
+users = UserSearch.call(name: "ali", role: %w[admin], sort: "name")
+```
+
+### What you get out of the box
+
+**11 built-in filter strategies** — `:eq`, `:not_eq`, `:contains`, `:starts_with`, `:ends_with`, `:gt`, `:gte`, `:lt`, `:lte`, `:in`, `:not_in`. Custom blocks for complex logic.
+
+**Sorting** with ascending/descending column sorts, custom sort blocks, and defaults.
+
+**`from_params`** — HTTP boundary handling with automatic coercion, blank stripping, and invalid value fallback:
+
+```ruby
+class UsersController < ApplicationController
+  def index
+    query = UserSearch.from_params(params, scope: policy_scope(User))
+    @users = pagy(query.resolve)
+  end
+end
+```
+
+**Form binding** — works with `form_with` for search forms. Queries respond to `model_name`, `param_key`, `persisted?`, and `to_params`.
+
+**Scope injection** — narrow the base scope at call time without modifying the query class.
+
 ## Installation
 
 ```ruby
@@ -214,6 +262,7 @@ Dexkit ships LLM-optimized guides. Copy them into your project so AI agents auto
 cp $(bundle show dexkit)/guides/llm/OPERATION.md app/operations/CLAUDE.md
 cp $(bundle show dexkit)/guides/llm/EVENT.md app/event_handlers/CLAUDE.md
 cp $(bundle show dexkit)/guides/llm/FORM.md app/forms/CLAUDE.md
+cp $(bundle show dexkit)/guides/llm/QUERY.md app/queries/CLAUDE.md
 ```
 
 ## License

data/Untitled

@@ -0,0 +1,12 @@
+P2
+Preserve explicit nils in `from_params` initialization
+from_params explicitly assigns nil for blank optional values, but new(**kwargs.compact) removes those keys before initialization. This breaks the documented "blank/invalid to nil" behavior whenever an optional prop has a non-nil default (prop? ... default: ...), because blank or uncoercible input silently falls back to the default and applies unintended filters.
+
+
+
+/Users/razorjack/Projects/OpenSource/dexkit/lib/dex/query.rb:134-134
+P3
+Validate `param_key` input before caching model name
+param_key accepts any truthy value and stores key.to_s without validation, so param_key "" is accepted but later crashes in model_name when ActiveModel::Name.new receives a blank class name. This turns a declaration-time DSL error into a runtime failure in form binding/from_params, which is harder to diagnose.
+/Users/razorjack/Projects/OpenSource/dexkit/lib/dex/query.rb:58-60
+

data/guides/llm/OPERATION.md

@@ -20,7 +20,12 @@ class CreateUser < Dex::Operation
   def perform
     error!(:invalid_email) unless email.include?("@")
     error!(:email_taken) if User.exists?(email: email)
-    User.create!(email: email, name: name, role: role)
+
+    user = User.create!(email: email, name: name, role: role)
+
+    after_commit { WelcomeMailer.with(user: user).deliver_later }
+
+    user
   end
 end
 ```
@@ -255,6 +260,25 @@ transaction :mongoid     # adapter override (default: auto-detect AR → Mongoid
 
 Child classes can re-enable: `transaction true`.
 
+### after_commit
+
+Register blocks to run after the transaction commits. Use for side effects that should only happen on success (emails, webhooks, cache invalidation):
+
+```ruby
+def perform
+  user = User.create!(name: name, email: email)
+  after_commit { WelcomeMailer.with(user: user).deliver_later }
+  after_commit { Analytics.track(:user_created, user_id: user.id) }
+  user
+end
+```
+
+On rollback (`error!` or exception), callbacks are discarded. When no transaction is open anywhere, executes immediately. Multiple blocks run in registration order.
+
+**ActiveRecord:** fully nesting-aware — callbacks are deferred until the outermost transaction commits, even across nested operations or ambient `ActiveRecord::Base.transaction` blocks. Requires Rails 7.2+.
+
+**Mongoid:** callbacks are deferred across nested Dex operations. Ambient `Mongoid.transaction` blocks opened outside Dex are not detected — callbacks will fire immediately in that case.
+
 ---
 
 ## Advisory Locking

data/guides/llm/QUERY.md

@@ -0,0 +1,348 @@
+# Dex::Query — LLM Reference
+
+Copy this to your app's queries directory (e.g., `app/queries/AGENTS.md`) so coding agents know the full API when implementing and testing queries.
+
+---
+
+## Reference Query
+
+All examples below build on this query unless noted otherwise:
+
+```ruby
+class UserSearch < Dex::Query
+  scope { User.all }
+
+  prop? :name,   String
+  prop? :role,   _Array(String)
+  prop? :age_min, Integer
+  prop? :status, String
+
+  filter :name,    :contains
+  filter :role,    :in
+  filter :age_min, :gte, column: :age
+  filter :status
+
+  sort :name, :created_at, default: "-created_at"
+  sort(:relevance) { |scope| scope.order(Arel.sql("LENGTH(name)")) }
+end
+```
+
+---
+
+## Defining Queries
+
+Queries declare a base scope, typed props for filter inputs, filter strategies, and sort columns.
+
+```ruby
+class ProjectSearch < Dex::Query
+  scope { Project.where(archived: false) }
+
+  prop? :name, String
+  filter :name, :contains
+
+  sort :name, :created_at, default: "name"
+end
+```
+
+### `scope { ... }`
+
+Required. Defines the base relation. The block is `instance_exec`'d so props are accessible:
+
+```ruby
+class TaskSearch < Dex::Query
+  scope { project.tasks }
+
+  prop :project, _Ref(Project)
+  prop? :status, String
+  filter :status
+end
+```
+
+### Props
+
+Uses the same `prop`/`prop?`/`_Ref` DSL as Operation and Event (powered by Literal):
+
+```ruby
+prop :project,  _Ref(Project)       # required, auto-finds by ID
+prop? :name,    String               # optional (nil by default)
+prop? :roles,   _Array(String)       # optional array
+prop? :age_min, Integer              # optional integer
+```
+
+Reserved prop names: `scope`, `sort`, `resolve`, `call`, `from_params`, `to_params`, `param_key`.
+
+---
+
+## Filters
+
+### Built-in Strategies
+
+| Strategy | SQL | Example |
+|----------|-----|---------|
+| `:eq` (default) | `= value` | `filter :status` |
+| `:not_eq` | `!= value` | `filter :status, :not_eq` |
+| `:contains` | `LIKE %value%` | `filter :name, :contains` |
+| `:starts_with` | `LIKE value%` | `filter :name, :starts_with` |
+| `:ends_with` | `LIKE %value` | `filter :name, :ends_with` |
+| `:gt` | `> value` | `filter :age, :gt` |
+| `:gte` | `>= value` | `filter :age_min, :gte, column: :age` |
+| `:lt` | `< value` | `filter :age, :lt` |
+| `:lte` | `<= value` | `filter :age, :lte` |
+| `:in` | `IN (values)` | `filter :roles, :in, column: :role` |
+| `:not_in` | `NOT IN (values)` | `filter :roles, :not_in, column: :role` |
+
+String strategies (`:contains`, `:starts_with`, `:ends_with`) use case-insensitive matching. With ActiveRecord, this uses Arel `matches` (LIKE); with Mongoid, case-insensitive regex. Wildcards in values are auto-sanitized. The adapter is auto-detected from the scope.
+
+### Column Mapping
+
+Map a prop name to a different column:
+
+```ruby
+prop? :age_min, Integer
+filter :age_min, :gte, column: :age
+```
+
+### Custom Filter Blocks
+
+For complex logic, use a block. Sanitize LIKE wildcards manually (built-in strategies handle this automatically):
+
+```ruby
+prop? :search, String
+filter(:search) do |scope, value|
+  sanitized = ActiveRecord::Base.sanitize_sql_like(value)
+  scope.where("name LIKE ? OR email LIKE ?", "%#{sanitized}%", "%#{sanitized}%")
+end
+```
+
+### Nil Skipping
+
+- Optional props (`prop?`) skip their filter when nil
+- `:in` / `:not_in` strategies also skip when value is nil or empty array
+
+---
+
+## Sorting
+
+### Column Sorts
+
+```ruby
+sort :name, :created_at, :age       # multiple columns at once
+sort :email                          # or one at a time
+```
+
+At call time, prefix with `-` for descending:
+
+```ruby
+UserSearch.call(sort: "name")        # ASC
+UserSearch.call(sort: "-created_at") # DESC
+```
+
+### Custom Sorts
+
+```ruby
+sort(:relevance) { |scope| scope.order(Arel.sql("LENGTH(name)")) }
+```
+
+Custom sorts cannot use the `-` prefix (direction is baked into the block).
+
+### Default Sort
+
+```ruby
+sort :name, :created_at, default: "-created_at"
+```
+
+Only one default per class. Applied when no sort is provided.
+
+---
+
+## Calling Queries
+
+### `.call`
+
+Returns an ActiveRecord relation:
+
+```ruby
+users = UserSearch.call(name: "ali", role: %w[admin], sort: "-name")
+users.each { |u| puts u.name }
+```
+
+### Shortcuts
+
+```ruby
+UserSearch.count(role: %w[admin])
+UserSearch.exists?(name: "Alice")
+UserSearch.any?(status: "active")
+```
+
+### Scope Injection
+
+Narrow the base scope without modifying the query class:
+
+```ruby
+active_users = User.where(active: true)
+UserSearch.call(scope: active_users, name: "ali")
+```
+
+The injected scope is merged via `.merge` — model must match.
+
+### Instance Usage
+
+```ruby
+query = UserSearch.new(name: "ali", sort: "-name")
+query.name    # => "ali"
+query.sort    # => "-name"
+result = query.resolve
+```
+
+---
+
+## `from_params` — HTTP Boundary
+
+Extracts, coerces, and validates params from a controller:
+
+```ruby
+UserSearch.from_params(params)
+UserSearch.from_params(params, scope: current_team.users)
+UserSearch.from_params(params, scope: current_team.users, project: current_project)
+```
+
+### What it does
+
+1. Extracts the nested hash from `params[param_key]` (e.g., `params[:user_search]`); falls back to flat params if the nested key is absent
+2. Extracts `sort` from that hash
+3. Strips blank strings to nil for optional props
+4. Compacts array blanks (`["admin", ""]` → `["admin"]`)
+5. Coerces strings to typed values (Integer, Date, etc.) — drops uncoercible to nil
+6. Skips `_Ref` typed props (must be passed as keyword overrides)
+7. Drops invalid sort values (falls back to default)
+8. Applies keyword overrides (pinned values)
+9. Returns a query instance
+
+### Controller Pattern
+
+```ruby
+class UsersController < ApplicationController
+  def index
+    query = UserSearch.from_params(params, scope: policy_scope(User))
+    @users = pagy(query.resolve)
+  end
+end
+```
+
+---
+
+## Form Binding
+
+Queries work with `form_with` for search forms:
+
+```ruby
+# Controller
+@query = UserSearch.from_params(params)
+
+# View
+<%= form_with model: @query, url: users_path, method: :get do |f| %>
+  <%= f.text_field :name %>
+  <%= f.select :role, %w[admin user], include_blank: true %>
+  <%= f.hidden_field :sort, value: @query.sort %>
+  <%= f.submit "Search" %>
+<% end %>
+```
+
+### `param_key`
+
+Override the default param key:
+
+```ruby
+class UserSearch < Dex::Query
+  param_key :q
+  # params[:q][:name] instead of params[:user_search][:name]
+end
+```
+
+### `model_name`
+
+Derives from class name by default. Anonymous classes fall back to "query".
+
+### `to_params`
+
+Returns a hash of non-nil prop values + current sort:
+
+```ruby
+query = UserSearch.new(name: "ali", sort: "-name")
+query.to_params  # => { name: "ali", sort: "-name" }
+```
+
+### `persisted?`
+
+Always returns `false` (queries are never persisted).
+
+---
+
+## Inheritance
+
+Subclasses inherit filters, sorts, and props. They can add new ones or replace the scope:
+
+```ruby
+class AdminUserSearch < UserSearch
+  scope { User.where(admin: true) }  # replaces parent scope
+
+  prop? :department, String
+  filter :department
+end
+```
+
+---
+
+## Testing
+
+Queries return standard ActiveRecord relations. Test them with plain Minitest:
+
+```ruby
+class UserSearchTest < Minitest::Test
+  def setup
+    User.create!(name: "Alice", role: "admin", age: 30)
+    User.create!(name: "Bob", role: "user", age: 25)
+  end
+
+  def test_filters_by_role
+    result = UserSearch.call(role: %w[admin])
+    assert_equal 1, result.count
+    assert_equal "Alice", result.first.name
+  end
+
+  def test_contains_search
+    result = UserSearch.call(name: "li")
+    assert_equal 1, result.count
+  end
+
+  def test_sorting
+    result = UserSearch.call(sort: "name")
+    assert_equal %w[Alice Bob], result.map(&:name)
+  end
+
+  def test_default_sort
+    result = UserSearch.call
+    assert_equal "Bob", result.first.name  # -created_at = newest first
+  end
+
+  def test_scope_injection
+    active = User.where(active: true)
+    result = UserSearch.call(scope: active, role: %w[user])
+    assert_equal 1, result.count
+  end
+
+  def test_from_params
+    params = ActionController::Parameters.new(
+      user_search: { name: "ali", sort: "-name" }
+    )
+    query = UserSearch.from_params(params)
+    assert_equal "ali", query.name
+    assert_equal "-name", query.sort
+  end
+
+  def test_to_params
+    query = UserSearch.new(name: "ali", sort: "-name")
+    assert_equal({ name: "ali", sort: "-name" }, query.to_params)
+  end
+end
+```

data/lib/dex/operation/transaction_adapter.rb

@@ -32,17 +32,63 @@ module Dex
           ActiveRecord::Base.transaction(&block)
         end
 
+        def self.after_commit(&block)
+          unless defined?(ActiveRecord) && ActiveRecord.respond_to?(:after_all_transactions_commit)
+            raise LoadError, "after_commit requires Rails 7.2+"
+          end
+
+          ActiveRecord.after_all_transactions_commit(&block)
+        end
+
         def self.rollback_exception_class
           ActiveRecord::Rollback
         end
       end
 
       module MongoidAdapter
+        AFTER_COMMIT_KEY = :_dex_mongoid_after_commit
+
         def self.wrap(&block)
           unless defined?(Mongoid)
             raise LoadError, "Mongoid is required for transactions"
           end
-          Mongoid.transaction(&block)
+
+          outermost = !Thread.current[AFTER_COMMIT_KEY]
+          Thread.current[AFTER_COMMIT_KEY] ||= []
+          snapshot = Thread.current[AFTER_COMMIT_KEY].length
+
+          block_completed = false
+          result = Mongoid.transaction do
+            value = block.call
+            block_completed = true
+            value
+          end
+
+          if outermost && block_completed
+            Thread.current[AFTER_COMMIT_KEY].each(&:call)
+          elsif !block_completed
+            # Mongoid swallowed a Rollback exception — discard callbacks from this level
+            Thread.current[AFTER_COMMIT_KEY].slice!(snapshot..)
+          end
+
+          result
+        rescue StandardError # rubocop:disable Style/RescueStandardError
+          Thread.current[AFTER_COMMIT_KEY]&.slice!(snapshot..) unless outermost
+          raise
+        ensure
+          Thread.current[AFTER_COMMIT_KEY] = nil if outermost
+        end
+
+        # NOTE: Only detects transactions opened via MongoidAdapter.wrap (i.e. Dex operations).
+        # Ambient Mongoid.transaction blocks opened outside Dex are invisible here —
+        # the callback will fire immediately instead of deferring to the outer commit.
+        def self.after_commit(&block)
+          callbacks = Thread.current[AFTER_COMMIT_KEY]
+          if callbacks
+            callbacks << block
+          else
+            block.call
+          end
         end
 
         def self.rollback_exception_class

data/lib/dex/operation/transaction_wrapper.rb

@@ -18,6 +18,17 @@ module Dex
       result
     end
 
+    def after_commit(&block)
+      raise ArgumentError, "after_commit requires a block" unless block
+
+      adapter = _transaction_adapter
+      if adapter
+        adapter.after_commit(&block)
+      else
+        block.call
+      end
+    end
+
     TRANSACTION_KNOWN_ADAPTERS = %i[active_record mongoid].freeze
 
     module ClassMethods

data/lib/dex/query/backend.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Dex
+  class Query
+    module Backend
+      STRATEGIES = %i[eq not_eq contains starts_with ends_with gt gte lt lte in not_in].to_set.freeze
+
+      module ActiveRecordAdapter
+        module_function
+
+        def apply(scope, strategy, column, value)
+          table = scope.arel_table
+
+          case strategy
+          when :eq, :in
+            scope.where(column => value)
+          when :not_eq, :not_in
+            scope.where.not(column => value)
+          when :contains
+            scope.where(table[column].matches("%#{sanitize_like(value)}%", "\\"))
+          when :starts_with
+            scope.where(table[column].matches("#{sanitize_like(value)}%", "\\"))
+          when :ends_with
+            scope.where(table[column].matches("%#{sanitize_like(value)}", "\\"))
+          when :gt
+            scope.where(table[column].gt(value))
+          when :gte
+            scope.where(table[column].gteq(value))
+          when :lt
+            scope.where(table[column].lt(value))
+          when :lte
+            scope.where(table[column].lteq(value))
+          else
+            raise ArgumentError, "Unknown strategy: #{strategy.inspect}"
+          end
+        end
+
+        def sanitize_like(value)
+          ActiveRecord::Base.sanitize_sql_like(value.to_s)
+        end
+      end
+
+      module MongoidAdapter
+        module_function
+
+        def apply(scope, strategy, column, value)
+          case strategy
+          when :eq
+            scope.where(column => value)
+          when :not_eq
+            scope.where(column.to_sym.ne => value)
+          when :in
+            scope.where(column.to_sym.in => Array(value))
+          when :not_in
+            scope.where(column.to_sym.nin => Array(value))
+          when :contains
+            scope.where(column => /#{Regexp.escape(value.to_s)}/i)
+          when :starts_with
+            scope.where(column => /\A#{Regexp.escape(value.to_s)}/i)
+          when :ends_with
+            scope.where(column => /#{Regexp.escape(value.to_s)}\z/i)
+          when :gt
+            scope.where(column.to_sym.gt => value)
+          when :gte
+            scope.where(column.to_sym.gte => value)
+          when :lt
+            scope.where(column.to_sym.lt => value)
+          when :lte
+            scope.where(column.to_sym.lte => value)
+          else
+            raise ArgumentError, "Unknown strategy: #{strategy.inspect}"
+          end
+        end
+      end
+
+      module_function
+
+      def apply_strategy(scope, strategy, column, value)
+        adapter_for(scope).apply(scope, strategy, column, value)
+      end
+
+      def adapter_for(scope)
+        if defined?(Mongoid::Criteria) && scope.is_a?(Mongoid::Criteria)
+          MongoidAdapter
+        else
+          ActiveRecordAdapter
+        end
+      end
+    end
+  end
+end

data/lib/dex/query/filtering.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Dex
+  class Query
+    module Filtering
+      extend Dex::Concern
+
+      FilterDef = Data.define(:name, :strategy, :column, :block, :optional)
+
+      module ClassMethods
+        def _filter_registry
+          @_filter_registry ||= {}
+        end
+
+        def filter(name, strategy = :eq, column: nil, &block)
+          name = name.to_sym
+
+          if _filter_registry.key?(name)
+            raise ArgumentError, "Filter :#{name} is already declared."
+          end
+
+          unless respond_to?(:literal_properties) && literal_properties.any? { |p| p.name == name }
+            raise ArgumentError, "Filter :#{name} requires a prop with the same name."
+          end
+
+          optional = _prop_optional?(name)
+
+          if block
+            _filter_registry[name] = FilterDef.new(name: name, strategy: nil, column: nil, block: block, optional: optional)
+          else
+            unless Backend::STRATEGIES.include?(strategy)
+              raise ArgumentError, "Unknown filter strategy: #{strategy.inspect}. " \
+                                   "Valid strategies: #{Backend::STRATEGIES.to_a.join(", ")}"
+            end
+
+            _filter_registry[name] = FilterDef.new(
+              name: name,
+              strategy: strategy,
+              column: (column || name).to_sym,
+              block: nil,
+              optional: optional
+            )
+          end
+        end
+
+        def filters
+          _filter_registry.keys
+        end
+      end
+
+      private
+
+      def _apply_filters(scope)
+        self.class._filter_registry.each_value do |filter_def|
+          value = public_send(filter_def.name)
+
+          next if value.nil? && filter_def.optional
+          next if (filter_def.strategy == :in || filter_def.strategy == :not_in) && value.respond_to?(:empty?) && value.empty?
+
+          result = if filter_def.block
+            instance_exec(scope, value, &filter_def.block)
+          else
+            Backend.apply_strategy(scope, filter_def.strategy, filter_def.column, value)
+          end
+
+          scope = result unless result.nil?
+        end
+
+        scope
+      end
+    end
+  end
+end

data/lib/dex/query/sorting.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Dex
+  class Query
+    module Sorting
+      extend Dex::Concern
+
+      SortDef = Data.define(:name, :custom, :block)
+
+      module ClassMethods
+        def _sort_registry
+          @_sort_registry ||= {}
+        end
+
+        def _sort_default
+          return @_sort_default if defined?(@_sort_default)
+
+          nil
+        end
+
+        def sort(*columns, default: nil, &block)
+          if block
+            raise ArgumentError, "Block sort requires exactly one column name." unless columns.size == 1
+
+            name = columns.first.to_sym
+
+            if _sort_registry.key?(name)
+              raise ArgumentError, "Sort :#{name} is already declared."
+            end
+
+            _sort_registry[name] = SortDef.new(name: name, custom: true, block: block)
+          else
+            raise ArgumentError, "sort requires at least one column name." if columns.empty?
+
+            columns.each do |col|
+              col = col.to_sym
+
+              if _sort_registry.key?(col)
+                raise ArgumentError, "Sort :#{col} is already declared."
+              end
+
+              _sort_registry[col] = SortDef.new(name: col, custom: false, block: nil)
+            end
+          end
+
+          if default
+            if defined?(@_sort_default) && @_sort_default
+              raise ArgumentError, "Default sort is already set to #{@_sort_default.inspect}."
+            end
+
+            bare = default.to_s.delete_prefix("-").to_sym
+            unless _sort_registry.key?(bare)
+              raise ArgumentError, "Default sort references unknown sort: #{bare.inspect}."
+            end
+
+            if default.to_s.start_with?("-") && _sort_registry[bare].custom
+              raise ArgumentError, "Custom sorts cannot use the \"-\" prefix."
+            end
+
+            @_sort_default = default.to_s
+          end
+        end
+
+        def sorts
+          _sort_registry.keys
+        end
+      end
+
+      private
+
+      def _apply_sort(scope)
+        sort_value = _current_sort
+        return scope unless sort_value
+
+        desc = sort_value.start_with?("-")
+        bare = sort_value.delete_prefix("-").to_sym
+
+        sort_def = self.class._sort_registry[bare]
+        unless sort_def
+          raise ArgumentError, "Unknown sort: #{bare.inspect}. Valid sorts: #{self.class._sort_registry.keys.join(", ")}"
+        end
+
+        if desc && sort_def.custom
+          raise ArgumentError, "Custom sorts cannot use the \"-\" prefix."
+        end
+
+        if sort_def.custom
+          instance_exec(scope, &sort_def.block)
+        else
+          scope.order(bare => desc ? :desc : :asc)
+        end
+      end
+    end
+  end
+end

data/lib/dex/query.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+require "active_model"
+
+require_relative "query/backend"
+require_relative "query/filtering"
+require_relative "query/sorting"
+
+module Dex
+  class Query
+    RESERVED_PROP_NAMES = %i[scope sort resolve call from_params to_params param_key].to_set.freeze
+
+    include PropsSetup
+    include Filtering
+    include Sorting
+
+    extend ActiveModel::Naming
+    include ActiveModel::Conversion
+
+    class << self
+      def scope(&block)
+        raise ArgumentError, "scope requires a block." unless block
+
+        @_scope_block = block
+      end
+
+      def _scope_block
+        return @_scope_block if defined?(@_scope_block)
+
+        superclass._scope_block if superclass.respond_to?(:_scope_block)
+      end
+
+      def new(scope: nil, sort: nil, **kwargs)
+        instance = super(**kwargs)
+        instance.instance_variable_set(:@_injected_scope, scope)
+        sort_str = sort&.to_s
+        sort_str = nil if sort_str&.empty?
+        instance.instance_variable_set(:@_sort_value, sort_str)
+        instance
+      end
+
+      def call(scope: nil, sort: nil, **kwargs)
+        new(scope: scope, sort: sort, **kwargs).resolve
+      end
+
+      def count(...)
+        call(...).count
+      end
+
+      def exists?(...)
+        call(...).exists?
+      end
+
+      def any?(...)
+        call(...).any?
+      end
+
+      def param_key(key = nil)
+        if key
+          str = key.to_s
+          raise ArgumentError, "param_key must not be blank." if str.empty?
+
+          @_param_key = str
+          @_model_name = nil
+        end
+        defined?(@_param_key) ? @_param_key : nil
+      end
+
+      silence_redefinition_of_method :model_name
+      def model_name
+        return @_model_name if @_model_name
+
+        pk = param_key
+        @_model_name = if pk
+          ActiveModel::Name.new(self, nil, pk.to_s.camelize).tap do |mn|
+            mn.define_singleton_method(:param_key) { pk }
+          end
+        elsif name && !name.start_with?("#")
+          super
+        else
+          ActiveModel::Name.new(self, nil, "Query")
+        end
+      end
+
+      def _prop_optional?(name)
+        return false unless respond_to?(:literal_properties)
+
+        prop = literal_properties.find { |p| p.name == name }
+        prop&.type.is_a?(Literal::Types::NilableType) || false
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@_filter_registry, _filter_registry.dup)
+        subclass.instance_variable_set(:@_sort_registry, _sort_registry.dup)
+        subclass.instance_variable_set(:@_sort_default, _sort_default) if _sort_default
+      end
+
+      def from_params(params, scope: nil, **overrides)
+        pk = model_name.param_key
+        nested = _extract_nested_params(params, pk)
+
+        sort_value = overrides.delete(:sort)&.to_s
+        unless sort_value && !sort_value.empty?
+          sort_value = nested.delete(:sort)&.to_s
+          sort_value = nil if sort_value && sort_value.empty?
+
+          # Validate sort — drop invalid to fall back to default
+          if sort_value
+            bare = sort_value.delete_prefix("-").to_sym
+            sort_def = _sort_registry[bare]
+            sort_value = nil if sort_def.nil? || (sort_value.start_with?("-") && sort_def.custom)
+          end
+        end
+
+        kwargs = {}
+
+        literal_properties.each do |prop|
+          pname = prop.name
+          next if overrides.key?(pname)
+          next if _ref_type?(prop.type)
+
+          raw = nested[pname]
+
+          if raw.nil? || (raw.is_a?(String) && raw.empty? && _prop_optional?(pname))
+            kwargs[pname] = nil if _prop_optional?(pname)
+            next
+          end
+
+          kwargs[pname] = _coerce_param(prop.type, raw)
+        end
+
+        kwargs.merge!(overrides)
+        kwargs[:sort] = sort_value if sort_value
+        kwargs[:scope] = scope if scope
+
+        new(**kwargs)
+      end
+
+      private
+
+      def _extract_nested_params(params, pk)
+        hash = if params.respond_to?(:to_unsafe_h)
+          params.to_unsafe_h
+        elsif params.is_a?(Hash)
+          params
+        else
+          {}
+        end
+
+        nested = hash[pk] || hash[pk.to_sym] || hash
+        nested = nested.to_unsafe_h if nested.respond_to?(:to_unsafe_h)
+        return {} unless nested.is_a?(Hash)
+
+        nested.transform_keys(&:to_sym)
+      end
+
+      def _ref_type?(type)
+        return true if type.is_a?(Dex::RefType)
+        return _ref_type?(type.type) if type.respond_to?(:type)
+
+        false
+      end
+
+      def _coerce_param(type, raw)
+        inner = type.is_a?(Literal::Types::NilableType) ? type.type : type
+
+        if inner.is_a?(Literal::Types::ArrayType)
+          values = Array(raw)
+          values = values.reject { |v| v.is_a?(String) && v.empty? }
+          return values.map { |v| _coerce_single(inner.type, v) }.compact
+        end
+
+        _coerce_single(inner, raw)
+      end
+
+      def _coerce_single(type, value)
+        return value unless value.is_a?(String)
+
+        base = _resolve_coercion_class(type)
+        return value unless base
+
+        case base.name
+        when "Integer"
+          Integer(value, 10)
+        when "Float"
+          Float(value)
+        when "Date"
+          Date.parse(value)
+        when "Time"
+          Time.parse(value)
+        when "DateTime"
+          DateTime.parse(value)
+        when "BigDecimal"
+          BigDecimal(value)
+        else
+          value
+        end
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      def _resolve_coercion_class(type)
+        return type if type.is_a?(Class)
+        return _resolve_coercion_class(type.type) if type.respond_to?(:type)
+
+        nil
+      end
+    end
+
+    def resolve
+      base = _evaluate_scope
+      base = _merge_injected_scope(base)
+      base = _apply_filters(base)
+      _apply_sort(base)
+    end
+
+    def sort
+      _current_sort
+    end
+
+    def to_params
+      result = {}
+
+      self.class.literal_properties.each do |prop|
+        value = public_send(prop.name)
+        result[prop.name] = value unless value.nil?
+      end
+
+      s = _current_sort
+      result[:sort] = s if s
+
+      result
+    end
+
+    def persisted?
+      false
+    end
+
+    private
+
+    def _current_sort
+      @_sort_value || self.class._sort_default
+    end
+
+    def _evaluate_scope
+      block = self.class._scope_block
+      raise ArgumentError, "No scope defined. Use `scope { Model.all }` in your Query class." unless block
+
+      instance_exec(&block)
+    end
+
+    def _merge_injected_scope(base)
+      return base unless @_injected_scope
+
+      unless base.respond_to?(:klass)
+        raise ArgumentError, "Scope block must return a queryable scope (ActiveRecord relation or Mongoid criteria), got #{base.class}."
+      end
+
+      unless @_injected_scope.respond_to?(:klass)
+        raise ArgumentError, "Injected scope must be a queryable scope (ActiveRecord relation or Mongoid criteria), got #{@_injected_scope.class}."
+      end
+
+      unless base.klass == @_injected_scope.klass
+        raise ArgumentError, "Scope model mismatch: expected #{base.klass}, got #{@_injected_scope.klass}."
+      end
+
+      base.merge(@_injected_scope)
+    end
+  end
+end

data/lib/dex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Dex
-  VERSION = "0.3.0"
+  VERSION = "0.4.1"
 end

data/lib/dexkit.rb

@@ -18,6 +18,7 @@ require_relative "dex/error"
 require_relative "dex/operation"
 require_relative "dex/event"
 require_relative "dex/form"
+require_relative "dex/query"
 
 module Dex
   class Configuration

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dexkit
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Jacek Galanciak
@@ -132,9 +132,11 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- Untitled
 - guides/llm/EVENT.md
 - guides/llm/FORM.md
 - guides/llm/OPERATION.md
+- guides/llm/QUERY.md
 - lib/dex/concern.rb
 - lib/dex/error.rb
 - lib/dex/event.rb
@@ -168,6 +170,10 @@ files:
 - lib/dex/operation/transaction_adapter.rb
 - lib/dex/operation/transaction_wrapper.rb
 - lib/dex/props_setup.rb
+- lib/dex/query.rb
+- lib/dex/query/backend.rb
+- lib/dex/query/filtering.rb
+- lib/dex/query/sorting.rb
 - lib/dex/ref_type.rb
 - lib/dex/test_helpers.rb
 - lib/dex/test_helpers/assertions.rb