dexkit 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3adbbfa21a62c17b74b7ac6807ed7a9abdca2b02c85e06bb2d542bdbf7d39677
-  data.tar.gz: cead77e688d4c30a7256c05f73d509fefd44c7c6b6bfc52d9b0bdbfd8675954e
+  metadata.gz: bc994e44218cf9063af69ad1d01929d86b91fe35b6f30769dd068832fb04fc37
+  data.tar.gz: b4a078fb25780824cd2a876f5d668196ba2f3a2094ce63a1b9731dfeab1c7aa6
 SHA512:
-  metadata.gz: b58aec14261efd1c679bb662b163df64f96d86239e5efe8897d7b8d007aef4cd19864a8fabc03ee4acf139379c1185e56f8a5f6e488a1f5dec00442a24223dee
-  data.tar.gz: 6009bd9567cf1fd4adacf21cfb5c6627cfce8d1d399498923ae9ff8a11c3f2b31df884549a8b3bdb0c45bede9951b672c6d50dbf2199a691e45a79c37b5c1497
+  metadata.gz: b4bb8dbbe3c9acd66e5c3ed6a6b203408f66c7455544c36de4e60e755a9cfa9a2fa3405a39648e77e5bd42b2593a053d5d517e16ce1cd5236225083bd24891b3
+  data.tar.gz: c050bd2dc477e19efcebbe6bfa6fe7d46dbfa4dea5367f38c098b6c82750439211d1b4a28224c21fd66e98c8971b9532f341f4e17b4d2e836383470ccf778913

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-03-03
+
+### Added
+
+- **Form objects** — `Dex::Form` base class for user-facing input handling
+  - Typed attributes via ActiveModel (`attribute :name, :string`)
+  - Normalization on assignment (`normalizes :email, with: -> { _1&.strip&.downcase }`)
+  - Full ActiveModel validation support, including custom `uniqueness` validator with scope, case-insensitive matching, conditions, and record exclusion
+  - `model` DSL for binding a form to an ActiveRecord model class (drives `model_name`, `persisted?`, `to_key`, `to_param`)
+  - `record` reader and `with_record` chainable method for edit/update forms — record is excluded from form attributes and protected from mass assignment
+  - `nested_one` / `nested_many` DSL for nested form objects with auto-generated constants, `build_` methods, and `_attributes=` setters
+  - Hash coercion, Rails numbered hash format, and `_destroy` filtering in nested forms
+  - Validation propagation from nested forms with prefixed error keys (`address.street`, `documents[0].doc_type`)
+  - `ActionController::Parameters` support — strong parameters (`permit`) not required; the form's attribute declarations are the whitelist
+  - `to_h` / `to_hash` serialization including nested forms
+  - `ValidationError` for bang-style save patterns
+  - Full Rails `form_with` / `fields_for` compatibility
+- **Form uniqueness validator** — `validates :email, uniqueness: true`
+  - Model resolution chain: explicit `model:` option, `model` DSL, or infer from class name (`UserForm` → `User`)
+  - Options: `scope`, `case_sensitive`, `conditions` (zero-arg or form-arg lambda), `attribute` mapping, `message`
+  - Excludes current record via model's `primary_key` (not hardcoded `id`)
+  - Declaration-time validation of `model:` and `conditions:` options
+- Added `actionpack` as development dependency for testing Rails controller integration
+- Added `activemodel >= 6.1` as runtime dependency
+
+### Changed
+
+- `Dex::Match` is now included in `Dex::Operation` – `Ok`/`Err` are available without prefix inside operations. External contexts (controllers, POROs) can still use `Dex::Ok`/`Dex::Err` or `include Dex::Match`.
+
 ## [0.2.0] - 2026-03-02
 
 ### Added

data/README.md

@@ -48,8 +48,6 @@ rescue_from Stripe::CardError, as: :card_declined
 **Ok / Err** – pattern match on operation outcomes with `.safe.call`:
 
 ```ruby
-include Dex::Match
-
 case CreateUser.new(email: email).safe.call
 in Ok(name:)
   puts "Welcome, #{name}!"
@@ -138,6 +136,109 @@ class CreateOrderTest < Minitest::Test
 end
 ```
 
+## Forms
+
+Form objects with typed attributes, normalization, nested forms, and Rails form builder compatibility.
+
+```ruby
+class OnboardingForm < Dex::Form
+  model User
+
+  attribute :first_name, :string
+  attribute :last_name, :string
+  attribute :email, :string
+
+  normalizes :email, with: -> { _1&.strip&.downcase.presence }
+
+  validates :email, presence: true, uniqueness: true
+  validates :first_name, :last_name, presence: true
+
+  nested_one :address do
+    attribute :street, :string
+    attribute :city, :string
+    validates :street, :city, presence: true
+  end
+end
+
+form = OnboardingForm.new(email: "  ALICE@EXAMPLE.COM  ", first_name: "Alice", last_name: "Smith")
+form.email  # => "alice@example.com"
+form.valid?
+```
+
+### What you get out of the box
+
+**ActiveModel attributes** with type casting, normalization, and full Rails validation DSL.
+
+**Nested forms** — `nested_one` and `nested_many` with automatic Hash coercion, `_destroy` support, and error propagation:
+
+```ruby
+nested_many :documents do
+  attribute :document_type, :string
+  attribute :document_number, :string
+  validates :document_type, :document_number, presence: true
+end
+```
+
+**Rails form compatibility** — works with `form_with`, `fields_for`, and nested attributes out of the box.
+
+**Uniqueness validation** against the database, with scope, case-sensitivity, and current-record exclusion.
+
+**Multi-model forms** — when a form spans User, Employee, and Address, define a `.for` convention method to map records and a `#save` method that delegates to a `Dex::Operation`:
+
+```ruby
+def save
+  return false unless valid?
+
+  case operation.safe.call
+  in Ok then true
+  in Err => e then errors.add(:base, e.message) and false
+  end
+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
@@ -155,6 +256,8 @@ Dexkit ships LLM-optimized guides. Copy them into your project so AI agents auto
 ```bash
 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/FORM.md

@@ -0,0 +1,520 @@
+# Dex::Form — LLM Reference
+
+Copy this to your app's forms directory (e.g., `app/forms/AGENTS.md`) so coding agents know the full API when implementing and testing forms.
+
+---
+
+## Reference Form
+
+All examples below build on this form unless noted otherwise:
+
+```ruby
+class OnboardingForm < Dex::Form
+  model User
+
+  attribute :first_name, :string
+  attribute :last_name, :string
+  attribute :email, :string
+  attribute :department, :string
+  attribute :start_date, :date
+
+  normalizes :email, with: -> { _1&.strip&.downcase.presence }
+
+  validates :email, presence: true, uniqueness: true
+  validates :first_name, :last_name, :department, presence: true
+  validates :start_date, presence: true
+
+  nested_one :address do
+    attribute :street, :string
+    attribute :city, :string
+    attribute :postal_code, :string
+    attribute :country, :string
+
+    validates :street, :city, :country, presence: true
+  end
+
+  nested_many :documents do
+    attribute :document_type, :string
+    attribute :document_number, :string
+
+    validates :document_type, :document_number, presence: true
+  end
+end
+```
+
+---
+
+## Defining Forms
+
+Forms use ActiveModel under the hood. Attributes are declared with `attribute` (same as ActiveModel::Attributes).
+
+```ruby
+class ProfileForm < Dex::Form
+  attribute :name, :string
+  attribute :age, :integer
+  attribute :bio, :string
+  attribute :active, :boolean, default: true
+  attribute :born_on, :date
+end
+```
+
+### Available types
+
+`:string`, `:integer`, `:float`, `:decimal`, `:boolean`, `:date`, `:datetime`, `:time`.
+
+### `model(klass)`
+
+Declares the backing model class. Used by:
+- `model_name` — delegates to model for Rails routing (`form_with model: @form`)
+- `validates :attr, uniqueness: true` — queries this model
+- `persisted?` — delegates to `record`
+
+```ruby
+class UserForm < Dex::Form
+  model User
+end
+```
+
+Optional. Multi-model forms often skip it.
+
+---
+
+## Normalization
+
+Uses Rails' `normalizes` (Rails 7.1+). Applied on every assignment.
+
+```ruby
+normalizes :email, with: -> { _1&.strip&.downcase.presence }
+normalizes :phone, with: -> { _1&.gsub(/\D/, "").presence }
+normalizes :name, :email, with: -> { _1&.strip.presence }   # multiple attrs
+```
+
+---
+
+## Validation
+
+Full ActiveModel validation DSL:
+
+```ruby
+validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+validates :name, presence: true, length: { minimum: 2, maximum: 100 }
+validates :role, inclusion: { in: %w[admin user] }
+validates :email, uniqueness: true                    # checks database
+validate :custom_validation_method
+```
+
+```ruby
+form.valid?              # => true/false
+form.invalid?            # => true/false
+form.errors              # => ActiveModel::Errors
+form.errors[:email]      # => ["can't be blank"]
+form.errors.full_messages # => ["Email can't be blank"]
+```
+
+### ValidationError
+
+```ruby
+error = Dex::Form::ValidationError.new(form)
+error.message  # => "Validation failed: Email can't be blank, Name can't be blank"
+error.form     # => the form instance
+```
+
+---
+
+## Nested Forms
+
+### `nested_one`
+
+One-to-one nested form. Automatically coerces Hash input.
+
+```ruby
+nested_one :address do
+  attribute :street, :string
+  attribute :city, :string
+  validates :street, :city, presence: true
+end
+```
+
+```ruby
+form = MyForm.new(address: { street: "123 Main", city: "NYC" })
+form.address.street         # => "123 Main"
+form.address.class          # => MyForm::Address (auto-generated)
+
+form.build_address(street: "456 Oak")  # build new nested
+form.address_attributes = { city: "Boston" }  # Rails compat setter
+```
+
+Default: initialized as empty form when not provided.
+
+### `nested_many`
+
+One-to-many nested form. Handles Array, Rails numbered Hash, and `_destroy`.
+
+```ruby
+nested_many :documents do
+  attribute :document_type, :string
+  attribute :document_number, :string
+  validates :document_type, :document_number, presence: true
+end
+```
+
+```ruby
+# Array of hashes
+form = MyForm.new(documents: [
+  { document_type: "passport", document_number: "AB123" },
+  { document_type: "visa", document_number: "CD456" }
+])
+
+# Rails numbered hash format (from form submissions)
+form = MyForm.new(documents: {
+  "0" => { document_type: "passport", document_number: "AB123" },
+  "1" => { document_type: "visa", document_number: "CD456" }
+})
+
+# _destroy support
+form = MyForm.new(documents: [
+  { document_type: "passport", document_number: "AB123" },
+  { document_type: "visa", document_number: "CD456", _destroy: "1" }  # filtered out
+])
+form.documents.size  # => 1
+
+form.build_document(document_type: "id_card")  # append new
+form.documents_attributes = { "0" => { document_type: "id_card" } }  # Rails compat setter
+```
+
+Default: initialized as `[]` when not provided.
+
+### `class_name` option
+
+Override the auto-generated constant name:
+
+```ruby
+nested_one :address, class_name: "HomeAddress" do
+  attribute :street, :string
+end
+# Creates MyForm::HomeAddress instead of MyForm::Address
+```
+
+### Validation propagation
+
+Nested errors bubble up with prefixed attribute names:
+
+```ruby
+form.valid?
+form.errors[:"address.street"]         # => ["can't be blank"]
+form.errors[:"documents[0].doc_type"]  # => ["can't be blank"]
+form.errors.full_messages
+# => ["Address street can't be blank", "Documents[0] doc type can't be blank"]
+```
+
+---
+
+## Uniqueness Validation
+
+Checks uniqueness against the database.
+
+```ruby
+validates :email, uniqueness: true
+```
+
+### Options
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `model:` | Explicit model class | `uniqueness: { model: User }` |
+| `attribute:` | Column name if different | `uniqueness: { attribute: :email }` |
+| `scope:` | Scoped uniqueness | `uniqueness: { scope: :tenant_id }` |
+| `case_sensitive:` | Case-insensitive check | `uniqueness: { case_sensitive: false }` |
+| `conditions:` | Extra query conditions | `uniqueness: { conditions: -> { where(active: true) } }` |
+| `message:` | Custom error message | `uniqueness: { message: "already registered" }` |
+
+### Model resolution
+
+1. `options[:model]` (explicit)
+2. `form.class._model_class` (from `model` DSL)
+3. Infer from class name: `RegistrationForm` → `Registration`
+4. If none found, validation is a no-op
+
+### Record exclusion
+
+When `form.record` is persisted, the current record is excluded from the uniqueness check (for updates).
+
+---
+
+## Record Binding
+
+Use `with_record` to associate a model instance with the form. This is the recommended approach in controllers – it keeps the record separate from user-submitted params.
+
+```ruby
+# Chainable — preferred in controllers
+form = OnboardingForm.new(params.require(:onboarding)).with_record(user)
+
+# Constructor hash — convenient in plain Ruby / tests
+form = OnboardingForm.new(name: "Alice", record: user)
+```
+
+```ruby
+form.record      # => the ActiveRecord instance (or nil)
+form.persisted?  # => true if record is present and persisted
+form.to_key      # => delegates to record (for URL generation)
+form.to_param    # => delegates to record
+```
+
+`record` is read-only after construction — there is no public `record=` setter.
+
+---
+
+## Serialization
+
+```ruby
+form.to_h
+# => {
+#   first_name: "Alice", last_name: "Smith", email: "alice@example.com",
+#   address: { street: "123 Main", city: "NYC", postal_code: nil, country: nil },
+#   documents: [{ document_type: "passport", document_number: "AB123" }]
+# }
+
+form.to_hash  # alias for to_h
+```
+
+---
+
+## Rails Integration
+
+### `form_with`
+
+```erb
+<%= form_with model: @form, url: onboarding_path do |f| %>
+  <%= f.text_field :first_name %>
+  <%= f.text_field :last_name %>
+  <%= f.email_field :email %>
+
+  <%= f.fields_for :address do |a| %>
+    <%= a.text_field :street %>
+    <%= a.text_field :city %>
+  <% end %>
+
+  <%= f.fields_for :documents do |d| %>
+    <%= d.text_field :document_type %>
+    <%= d.text_field :document_number %>
+    <%= d.hidden_field :_destroy %>
+  <% end %>
+
+  <%= f.submit %>
+<% end %>
+```
+
+### Controller pattern
+
+Strong parameters (`permit`) are not required — the form's attribute declarations are the whitelist. Just `require` the top-level key:
+
+```ruby
+class OnboardingController < ApplicationController
+  def new
+    @form = OnboardingForm.new
+  end
+
+  def create
+    @form = OnboardingForm.new(params.require(:onboarding))
+
+    if @form.save
+      redirect_to dashboard_path
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+
+  def edit
+    @form = OnboardingForm.for(current_user)
+  end
+
+  def update
+    @form = OnboardingForm.new(params.require(:onboarding)).with_record(current_user)
+
+    if @form.save
+      redirect_to dashboard_path
+    else
+      render :edit, status: :unprocessable_entity
+    end
+  end
+end
+```
+
+---
+
+## Suggested Conventions
+
+Dex::Form handles data holding, normalization, and validation. Persistence and record mapping are user-defined. These conventions are recommended:
+
+### `.for(record)` — load from record
+
+```ruby
+class OnboardingForm < Dex::Form
+  def self.for(user)
+    employee = user.employee
+
+    new(
+      first_name: user.first_name,
+      last_name: user.last_name,
+      email: user.email,
+      department: employee.department,
+      start_date: employee.start_date,
+      address: {
+        street: employee.address.street, city: employee.address.city,
+        postal_code: employee.address.postal_code, country: employee.address.country
+      },
+      documents: employee.documents.map { |d|
+        { document_type: d.document_type, document_number: d.document_number }
+      }
+    ).with_record(user)
+  end
+end
+```
+
+### `#save` — persist via Operation
+
+```ruby
+class OnboardingForm < Dex::Form
+  def save
+    return false unless valid?
+
+    case operation.safe.call
+    in Ok then true
+    in Err => e then errors.add(:base, e.message) and false
+    end
+  end
+
+  private
+
+  def operation
+    Onboarding::Upsert.new(
+      user: record, first_name:, last_name:, email:,
+      department:, start_date:,
+      address: address.to_h,
+      documents: documents.map(&:to_h)
+    )
+  end
+end
+```
+
+---
+
+## Complete Example
+
+A form spanning User, Employee, and Address — the core reason form objects exist.
+
+```ruby
+class OnboardingForm < Dex::Form
+  attribute :first_name, :string
+  attribute :last_name, :string
+  attribute :email, :string
+  attribute :department, :string
+  attribute :position, :string
+  attribute :start_date, :date
+
+  normalizes :email, with: -> { _1&.strip&.downcase.presence }
+
+  validates :email, presence: true, uniqueness: { model: User }
+  validates :first_name, :last_name, :department, :position, presence: true
+  validates :start_date, presence: true
+
+  nested_one :address do
+    attribute :street, :string
+    attribute :city, :string
+    attribute :postal_code, :string
+    attribute :country, :string
+
+    validates :street, :city, :country, presence: true
+  end
+
+  nested_many :documents do
+    attribute :document_type, :string
+    attribute :document_number, :string
+
+    validates :document_type, :document_number, presence: true
+  end
+
+  def self.for(user)
+    employee = user.employee
+
+    new(
+      first_name: user.first_name,
+      last_name: user.last_name,
+      email: user.email,
+      department: employee.department,
+      position: employee.position,
+      start_date: employee.start_date,
+      address: {
+        street: employee.address.street, city: employee.address.city,
+        postal_code: employee.address.postal_code, country: employee.address.country
+      },
+      documents: employee.documents.map { |d|
+        { document_type: d.document_type, document_number: d.document_number }
+      }
+    ).with_record(user)
+  end
+
+  def save
+    return false unless valid?
+
+    case operation.safe.call
+    in Ok then true
+    in Err => e then errors.add(:base, e.message) and false
+    end
+  end
+
+  private
+
+  def operation
+    Onboarding::Upsert.new(
+      user: record, first_name:, last_name:, email:,
+      department:, position:, start_date:,
+      address: address.to_h,
+      documents: documents.map(&:to_h)
+    )
+  end
+end
+```
+
+---
+
+## Testing
+
+Forms are standard ActiveModel objects. Test them with plain Minitest — no special helpers needed.
+
+```ruby
+class OnboardingFormTest < Minitest::Test
+  def test_validates_required_fields
+    form = OnboardingForm.new
+    assert form.invalid?
+    assert form.errors[:email].any?
+    assert form.errors[:first_name].any?
+  end
+
+  def test_normalizes_email
+    form = OnboardingForm.new(email: "  ALICE@EXAMPLE.COM  ")
+    assert_equal "alice@example.com", form.email
+  end
+
+  def test_nested_validation_propagation
+    form = OnboardingForm.new(
+      first_name: "Alice", last_name: "Smith",
+      email: "alice@example.com", department: "Eng",
+      position: "Developer", start_date: Date.today,
+      address: { street: "", city: "", country: "" }
+    )
+    assert form.invalid?
+    assert form.errors[:"address.street"].any?
+  end
+
+  def test_to_h_serialization
+    form = OnboardingForm.new(
+      first_name: "Alice", email: "alice@example.com",
+      address: { street: "123 Main", city: "NYC" }
+    )
+    h = form.to_h
+    assert_equal "Alice", h[:first_name]
+    assert_equal "123 Main", h[:address][:street]
+  end
+end
+```