dexkit 0.2.0 → 0.4.0

data/guides/llm/OPERATION.md

@@ -187,7 +187,7 @@ in Dex::Err(code: :email_taken) then puts "Already exists"
 end
 ```
 
-`include Dex::Match` to use `Ok`/`Err` without `Dex::` prefix.
+`Ok`/`Err` are available inside operations without prefix. In other contexts (controllers, POROs), use `Dex::Ok`/`Dex::Err` or `include Dex::Match`.
 
 ---
 

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/form/nesting.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Dex
+  class Form
+    module Nesting
+      extend Dex::Concern
+
+      module ClassMethods
+        def _nested_ones
+          @_nested_ones ||= {}
+        end
+
+        def _nested_manys
+          @_nested_manys ||= {}
+        end
+
+        def nested_one(name, class_name: nil, &block)
+          raise ArgumentError, "nested_one requires a block" unless block
+
+          name = name.to_sym
+          nested_class = _build_nested_class(name, class_name, &block)
+          _nested_ones[name] = nested_class
+
+          attr_reader name
+
+          define_method(:"#{name}=") do |value|
+            coerced = _coerce_nested_one(name, value)
+            instance_variable_set(:"@#{name}", coerced)
+          end
+
+          define_method(:"build_#{name}") do |attrs = {}|
+            instance = self.class._nested_ones[name].new(attrs)
+            send(:"#{name}=", instance)
+            instance
+          end
+
+          define_method(:"#{name}_attributes=") do |attrs|
+            send(:"#{name}=", attrs)
+          end
+        end
+
+        def nested_many(name, class_name: nil, &block)
+          raise ArgumentError, "nested_many requires a block" unless block
+
+          name = name.to_sym
+          nested_class = _build_nested_class(name, class_name, &block)
+          _nested_manys[name] = nested_class
+
+          attr_reader name
+
+          define_method(:"#{name}=") do |value|
+            coerced = _coerce_nested_many(name, value)
+            instance_variable_set(:"@#{name}", coerced)
+          end
+
+          define_method(:"build_#{name.to_s.singularize}") do |attrs = {}|
+            instance = self.class._nested_manys[name].new(attrs)
+            items = send(name) || []
+            items << instance
+            instance_variable_set(:"@#{name}", items)
+            instance
+          end
+
+          define_method(:"#{name}_attributes=") do |attrs|
+            send(:"#{name}=", attrs)
+          end
+        end
+
+        private
+
+        def _build_nested_class(name, class_name, &block)
+          klass = Class.new(Dex::Form, &block)
+          const_name = class_name || name.to_s.singularize.camelize
+          const_set(const_name, klass)
+          klass
+        end
+      end
+
+      private
+
+      def _coerce_nested_one(name, value)
+        klass = self.class._nested_ones[name]
+        value = _unwrap_hash_like(value)
+        case value
+        when Hash
+          return nil if _marked_for_destroy?(value)
+          klass.new(value.except("_destroy", :_destroy))
+        when klass then value
+        when nil then value
+        else raise ArgumentError, "#{name} must be a Hash or #{klass}, got #{value.class}"
+        end
+      end
+
+      def _coerce_nested_many(name, value)
+        klass = self.class._nested_manys[name]
+        value = _unwrap_hash_like(value)
+        items = case value
+        when Array then value
+        when Hash then _normalize_nested_hash(value)
+        else raise ArgumentError, "#{name} must be an Array or Hash, got #{value.class}"
+        end
+
+        items.filter_map do |item|
+          item = _unwrap_hash_like(item)
+          case item
+          when Hash
+            next nil if _marked_for_destroy?(item)
+            klass.new(item.except("_destroy", :_destroy))
+          when klass then item
+          else raise ArgumentError, "each #{name} item must be a Hash or #{klass}"
+          end
+        end
+      end
+
+      def _unwrap_hash_like(value)
+        return value.to_unsafe_h if value.respond_to?(:to_unsafe_h)
+        return value if value.is_a?(Hash) || value.is_a?(Array) || value.is_a?(Dex::Form) || value.nil?
+
+        value.respond_to?(:to_h) ? value.to_h : value
+      end
+
+      def _normalize_nested_hash(hash)
+        hash.sort_by { |k, _| k.to_s.to_i }.map(&:last)
+      end
+
+      def _marked_for_destroy?(attrs)
+        destroy_val = attrs["_destroy"] || attrs[:_destroy]
+        ActiveModel::Type::Boolean.new.cast(destroy_val)
+      end
+
+      def _initialize_nested_defaults(provided_keys)
+        self.class._nested_ones.each_key do |name|
+          key = name.to_s
+          next if provided_keys.include?(key) || provided_keys.include?("#{key}_attributes")
+
+          send(:"#{name}=", {})
+        end
+
+        self.class._nested_manys.each_key do |name|
+          next if instance_variable_get(:"@#{name}")
+
+          instance_variable_set(:"@#{name}", [])
+        end
+      end
+
+      def _validate_nested(context)
+        valid = true
+
+        self.class._nested_ones.each_key do |name|
+          nested = send(name)
+          next unless nested
+
+          unless nested.valid?(context)
+            nested.errors.each do |error|
+              errors.add(:"#{name}.#{error.attribute}", error.message)
+            end
+            valid = false
+          end
+        end
+
+        self.class._nested_manys.each_key do |name|
+          items = send(name) || []
+          items.each_with_index do |item, index|
+            next if item.valid?(context)
+
+            item.errors.each do |error|
+              errors.add(:"#{name}[#{index}].#{error.attribute}", error.message)
+            end
+            valid = false
+          end
+        end
+
+        valid
+      end
+
+      def _nested_to_h(result)
+        self.class._nested_ones.each_key do |name|
+          nested = send(name)
+          result[name] = nested&.to_h
+        end
+
+        self.class._nested_manys.each_key do |name|
+          items = send(name) || []
+          result[name] = items.map(&:to_h)
+        end
+      end
+    end
+  end
+end

data/lib/dex/form/uniqueness_validator.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Dex
+  class Form
+    class UniquenessValidator < ActiveModel::EachValidator
+      def check_validity!
+        if options.key?(:model) && !options[:model].is_a?(Class)
+          raise ArgumentError, "uniqueness :model must be a Class, got #{options[:model].inspect}"
+        end
+        if options.key?(:conditions) && !options[:conditions].respond_to?(:call)
+          raise ArgumentError, "uniqueness :conditions must be callable"
+        end
+      end
+
+      def validate_each(form, attribute, value)
+        return if value.blank?
+
+        model_class = _resolve_model_class(form)
+        return unless model_class
+
+        column = options[:attribute] || attribute
+        query = _build_query(model_class, column, value)
+        query = _apply_scope(query, form)
+        query = _apply_conditions(query, form)
+        query = _exclude_current_record(query, form)
+
+        form.errors.add(attribute, options[:message] || :taken) if query.exists?
+      end
+
+      private
+
+      def _resolve_model_class(form)
+        return options[:model] if options[:model]
+        return form.class._model_class if form.class.respond_to?(:_model_class) && form.class._model_class
+
+        _infer_model_class(form)
+      end
+
+      def _infer_model_class(form)
+        class_name = form.class.name
+        return unless class_name
+
+        model_name = class_name.sub(/Form\z/, "")
+        return if model_name == class_name
+
+        klass = Object.const_get(model_name)
+        klass.respond_to?(:where) ? klass : nil
+      rescue NameError
+        nil
+      end
+
+      def _build_query(model_class, column, value)
+        if options[:case_sensitive] == false && value.is_a?(String) && model_class.respond_to?(:arel_table)
+          model_class.where(model_class.arel_table[column].lower.eq(value.downcase))
+        else
+          model_class.where(column => value)
+        end
+      end
+
+      def _apply_scope(query, form)
+        Array(options[:scope]).each do |scope_attr|
+          query = query.where(scope_attr => form.public_send(scope_attr))
+        end
+        query
+      end
+
+      def _apply_conditions(query, form)
+        return query unless options[:conditions]
+
+        callable = options[:conditions]
+        if callable.arity.zero?
+          query.instance_exec(&callable)
+        else
+          query.instance_exec(form, &callable)
+        end
+      end
+
+      def _exclude_current_record(query, form)
+        return query unless form.record&.persisted?
+
+        pk = form.record.class.primary_key
+        query.where.not(pk => form.record.public_send(pk))
+      end
+    end
+  end
+end