dexkit 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3adbbfa21a62c17b74b7ac6807ed7a9abdca2b02c85e06bb2d542bdbf7d39677
-  data.tar.gz: cead77e688d4c30a7256c05f73d509fefd44c7c6b6bfc52d9b0bdbfd8675954e
+  metadata.gz: ec8b561633fbdf9989f8bc2476fe84ad2cd0c32177990d03380d63f59a8368a9
+  data.tar.gz: a348e6b1090374bfda6281e6a58fe16af3e285bb009fad38be60a3ba2c510720
 SHA512:
-  metadata.gz: b58aec14261efd1c679bb662b163df64f96d86239e5efe8897d7b8d007aef4cd19864a8fabc03ee4acf139379c1185e56f8a5f6e488a1f5dec00442a24223dee
-  data.tar.gz: 6009bd9567cf1fd4adacf21cfb5c6627cfce8d1d399498923ae9ff8a11c3f2b31df884549a8b3bdb0c45bede9951b672c6d50dbf2199a691e45a79c37b5c1497
+  metadata.gz: 49d44b87657f65927b88c7fc1296ccab5d5246637a1887a126b0949e11bd452ecc0deb5fea90ef7f3329051b7bc13895f8f0ef73286705de44f7d21dccc0802a
+  data.tar.gz: 43182a4b6b6c904afe87fb385cff3a42057975363b5fd53e10744264f3af8cd5d48306b0ade26fd195b0d4fca696cbd85ac6c06e4434f48c280fb42a959beb80

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,66 @@ 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
+```
+
 ## Installation
 
 ```ruby
@@ -155,6 +213,7 @@ 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
 ```
 
 ## License

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
+```

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/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

data/lib/dex/form.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "active_model"
+
+require_relative "form/nesting"
+
+module Dex
+  class Form
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+    include ActiveModel::Validations::Callbacks
+
+    if defined?(ActiveModel::Attributes::Normalization)
+      include ActiveModel::Attributes::Normalization
+    end
+
+    include Nesting
+    include Match
+
+    class ValidationError < StandardError
+      attr_reader :form
+
+      def initialize(form)
+        @form = form
+        super("Validation failed: #{form.errors.full_messages.join(", ")}")
+      end
+    end
+
+    class << self
+      def model(klass = nil)
+        if klass
+          raise ArgumentError, "model must be a Class, got #{klass.inspect}" unless klass.is_a?(Class)
+          @_model_class = klass
+        end
+        _model_class
+      end
+
+      def _model_class
+        return @_model_class if defined?(@_model_class)
+        superclass._model_class if superclass.respond_to?(:_model_class)
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@_nested_ones, _nested_ones.dup)
+        subclass.instance_variable_set(:@_nested_manys, _nested_manys.dup)
+      end
+    end
+
+    silence_redefinition_of_method :model_name
+    def self.model_name
+      if _model_class
+        _model_class.model_name
+      elsif name && !name.start_with?("#")
+        super
+      else
+        @_model_name ||= ActiveModel::Name.new(self, nil, name&.split("::")&.last || "Form")
+      end
+    end
+
+    attr_reader :record
+
+    def initialize(attributes = {})
+      # Accept ActionController::Parameters without requiring .permit — the form's
+      # attribute declarations are the whitelist. Only declared attributes and nested
+      # setters are assignable; everything else is silently dropped.
+      attributes = attributes.to_unsafe_h if attributes.respond_to?(:to_unsafe_h)
+      attrs = (attributes || {}).transform_keys(&:to_s)
+      record = attrs.delete("record")
+      @record = record if record.nil? || record.respond_to?(:persisted?)
+      provided_keys = attrs.keys
+      nested_attrs = _extract_nested_attributes(attrs)
+      super(attrs.slice(*self.class.attribute_names))
+      _apply_nested_attributes(nested_attrs)
+      _initialize_nested_defaults(provided_keys)
+    end
+
+    def with_record(record)
+      raise ArgumentError, "record must respond to #persisted?, got #{record.inspect}" unless record.respond_to?(:persisted?)
+
+      @record = record
+      self
+    end
+
+    def persisted?
+      record&.persisted? || false
+    end
+
+    def to_key
+      record&.to_key
+    end
+
+    def to_param
+      record&.to_param
+    end
+
+    def valid?(context = nil)
+      super_result = super
+      nested_result = _validate_nested(context)
+      super_result && nested_result
+    end
+
+    def to_h
+      result = {}
+      self.class.attribute_names.each do |name|
+        result[name.to_sym] = public_send(name)
+      end
+      _nested_to_h(result)
+      result
+    end
+
+    alias_method :to_hash, :to_h
+
+    private
+
+    def _extract_nested_attributes(attrs)
+      nested_keys = self.class._nested_ones.keys.map(&:to_s) +
+        self.class._nested_manys.keys.map(&:to_s)
+
+      extracted = {}
+      nested_keys.each do |key|
+        attr_key = "#{key}_attributes"
+        if attrs.key?(attr_key)
+          extracted[attr_key] = attrs.delete(attr_key)
+          attrs.delete(key)
+        elsif attrs.key?(key)
+          extracted[key] = attrs.delete(key)
+        end
+      end
+      extracted
+    end
+
+    def _apply_nested_attributes(nested_attrs)
+      nested_attrs.each do |key, value|
+        next if value.nil?
+        send(:"#{key}=", value)
+      end
+    end
+  end
+end
+
+require_relative "form/uniqueness_validator"

data/lib/dex/operation.rb

@@ -139,3 +139,6 @@ require_relative "operation/jobs"
 
 # Top-level aliases (depend on Operation::Ok/Err)
 require_relative "match"
+
+# Make Ok/Err available without prefix inside operations
+Dex::Operation.include(Dex::Match)

data/lib/dex/version.rb

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

data/lib/dexkit.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dexkit
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Jacek Galanciak
@@ -9,6 +9,20 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
 - !ruby/object:Gem::Dependency
   name: literal
   requirement: !ruby/object:Gem::Requirement
@@ -65,6 +79,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
@@ -93,8 +121,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.1'
-description: 'A toolbelt of patterns for your Rails applications: Operation (more
-  coming soon)'
+description: 'A toolbelt of patterns for your Rails applications: Operation, Event,
+  Form'
 email:
 - jacek.galanciak@gmail.com
 executables: []
@@ -105,6 +133,7 @@ files:
 - LICENSE.txt
 - README.md
 - guides/llm/EVENT.md
+- guides/llm/FORM.md
 - guides/llm/OPERATION.md
 - lib/dex/concern.rb
 - lib/dex/error.rb
@@ -118,6 +147,9 @@ files:
 - lib/dex/event/trace.rb
 - lib/dex/event_test_helpers.rb
 - lib/dex/event_test_helpers/assertions.rb
+- lib/dex/form.rb
+- lib/dex/form/nesting.rb
+- lib/dex/form/uniqueness_validator.rb
 - lib/dex/match.rb
 - lib/dex/operation.rb
 - lib/dex/operation/async_proxy.rb