Active Model and form objects

# A form object built on plain Ruby classes and Active Model alone.
# ActiveModel::API gives naming, conversion, attribute assignment and
# validations, so form_with and the error helpers accept the object;
# ActiveModel::Attributes gives typed attributes with defaults; and
# ActiveModel::Attributes::Normalization (new in Rails 8.1) adds normalizes.
# Nothing here starts a server or opens a database.
require "active_model"

# A fee split into base, GST and total, kept in paise (100 paise make a rupee)
# so that every sum is a whole number. Data.define builds an immutable value.
FeeBreakdown = Data.define(:plan, :base_paise, :gst_paise, :total_paise) do
  def rupees(paise) = format("Rs %.2f", paise / 100.0)
end

# Kaksha's fee plans, and the 18 % GST it adds to each of them.
PLAN_PAISE = { "monthly" => 60_000, "term" => 150_000, "year" => 480_000 }.freeze
GST_PERCENT = 18

def fee_for(plan)
  base = PLAN_PAISE.fetch(plan)
  gst = base * GST_PERCENT / 100
  FeeBreakdown.new(plan: plan, base_paise: base, gst_paise: gst, total_paise: base + gst)
end

class Student
  include ActiveModel::API
  include ActiveModel::Attributes

  attribute :name, :string
  attribute :grade, :integer

  validates :name, presence: true, length: { maximum: 80 }
  validates :grade, numericality: { only_integer: true, greater_than_or_equal_to: 1, less_than_or_equal_to: 12 }
end

class Guardian
  include ActiveModel::API
  include ActiveModel::Attributes
  include ActiveModel::Attributes::Normalization

  attribute :name, :string
  attribute :phone, :string

  # Keep the digits, drop the 0 of an 11-digit number or the 91 of a 12-digit
  # one, and write +91 before the ten digits left. Any other length stays as
  # bare digits for the format rule to refuse. Running it twice changes nothing.
  normalizes :phone, with: ->(value) do
    digits = value.gsub(/\D/, "")
    digits = digits.delete_prefix("0") if digits.length == 11
    digits = digits.delete_prefix("91") if digits.length == 12
    digits.length == 10 ? "+91#{digits}" : digits
  end

  validates :name, presence: true
  validates :phone, format: { with: /\A\+91[6-9]\d{9}\z/, message: "must be an Indian mobile" }
end

# The form object: one screen that enrols a student with a guardian and a fee
# plan. It validates itself and both records, and copies their messages onto
# its own errors so that a view reads them in one place.
class EnrolmentForm
  include ActiveModel::API
  include ActiveModel::Attributes

  attribute :student_name, :string
  attribute :student_grade, :integer
  attribute :guardian_name, :string
  attribute :guardian_phone, :string
  attribute :fee_plan, :string, default: "monthly"

  validates :fee_plan, inclusion: { in: PLAN_PAISE.keys }

  def student
    @student ||= Student.new(name: student_name, grade: student_grade)
  end

  def guardian
    # Assigning the phone runs the normalizer, so the Guardian holds the clean one.
    @guardian ||= Guardian.new(name: guardian_name, phone: guardian_phone)
  end

  def fee
    fee_for(fee_plan) if PLAN_PAISE.key?(fee_plan)
  end

  # True only when the form and both records are valid. Every message of a
  # record is copied onto the form as student_name, guardian_phone and so on.
  def validate_all
    valid?
    { student: student, guardian: guardian }.each do |prefix, record|
      next if record.valid?
      record.errors.each { |err| errors.add(:"#{prefix}_#{err.attribute}", err.message) }
    end
    errors.empty?
  end
end

# The runs below happen when this file is run, not when a test requires it.
if __FILE__ == $PROGRAM_NAME
  def show(label, form)
    puts "== #{label} =="
    ok = form.validate_all
    puts "  stored guardian.phone -> #{form.guardian.phone.inspect}"
    puts "  valid? -> #{ok}"
    if ok
      f = form.fee
      puts "  fee for #{f.plan}: base #{f.rupees(f.base_paise)}, GST #{f.rupees(f.gst_paise)}, total #{f.rupees(f.total_paise)}"
    else
      form.errors.full_messages.each { |m| puts "  - #{m}" }
    end
    puts
  end

  puts "== What form_with and the casts see =="
  blank = EnrolmentForm.new(student_grade: "10")
  puts "  model_name.param_key -> #{blank.model_name.param_key.inspect}, persisted? -> #{blank.persisted?}"
  puts "  student_grade posted as \"10\" -> #{blank.student_grade.inspect}, as \"\" -> #{EnrolmentForm.new(student_grade: "").student_grade.inspect}"
  puts "  fee_plan when nothing is posted -> #{blank.fee_plan.inspect}"
  puts

  puts "== One mobile typed four ways, then a landline =="
  ["+91 98765-43210", "098765 43210", "919876543210", "9876543210", "011 2345 6789"].each do |typed|
    g = Guardian.new(name: "Sita Kumar", phone: typed)
    puts format("  %-17s -> %-16s valid? %s", typed.inspect, g.phone.inspect, g.valid?)
  end
  once = Guardian.normalize_value_for(:phone, "098765 43210")
  puts "  normalized once -> #{once.inspect}, twice -> #{Guardian.normalize_value_for(:phone, once).inspect}"
  puts

  show("A good enrolment",
       EnrolmentForm.new(student_name: "Ravi Kumar", student_grade: "10",
                         guardian_name: "Sita Kumar", guardian_phone: "+91 98765-43210", fee_plan: "term"))

  show("Bad input in every field",
       EnrolmentForm.new(student_name: "", student_grade: "15",
                         guardian_name: "", guardian_phone: "011 2345 6789", fee_plan: "quarterly"))

  puts "== A fee value that cannot change =="
  fee = fee_for("year")
  puts "  year plan: #{fee.rupees(fee.base_paise)} + #{fee.rupees(fee.gst_paise)} GST = #{fee.rupees(fee.total_paise)}"
  puts "  frozen? -> #{fee.frozen?}, a total_paise= writer? -> #{fee.respond_to?(:total_paise=)}"
  copy = fee.with(total_paise: 0)
  puts "  with(total_paise: 0) built a new value (#{copy.rupees(copy.total_paise)}); the first still says #{fee.rupees(fee.total_paise)}"
  begin
    fee.instance_variable_set(:@note, "discount")
  rescue FrozenError => e
    puts "  adding state raised FrozenError: #{e.message}"
  end
end

== What form_with and the casts see ==
  model_name.param_key -> "enrolment_form", persisted? -> false
  student_grade posted as "10" -> 10, as "" -> nil
  fee_plan when nothing is posted -> "monthly"

== One mobile typed four ways, then a landline ==
  "+91 98765-43210" -> "+919876543210"  valid? true
  "098765 43210"    -> "+919876543210"  valid? true
  "919876543210"    -> "+919876543210"  valid? true
  "9876543210"      -> "+919876543210"  valid? true
  "011 2345 6789"   -> "+911123456789"  valid? false
  normalized once -> "+919876543210", twice -> "+919876543210"

== A good enrolment ==
  stored guardian.phone -> "+919876543210"
  valid? -> true
  fee for term: base Rs 1500.00, GST Rs 270.00, total Rs 1770.00

== Bad input in every field ==
  stored guardian.phone -> "+911123456789"
  valid? -> false
  - Fee plan is not included in the list
  - Student name can't be blank
  - Student grade must be less than or equal to 12
  - Guardian name can't be blank
  - Guardian phone must be an Indian mobile

== A fee value that cannot change ==
  year plan: Rs 4800.00 + Rs 864.00 GST = Rs 5664.00
  frozen? -> true, a total_paise= writer? -> false
  with(total_paise: 0) built a new value (Rs 0.00); the first still says Rs 5664.00
  adding state raised FrozenError: can't modify frozen FeeBreakdown: #<data FeeBreakdown plan="year", base_paise=480000, gst_paise=86400, total_paise=566400>

# The enrolment form object again, now in front of three Active Record tables
# in an in-memory SQLite database that lives only for this run. save checks
# the form and every record first, then writes all three inside one
# transaction, so a write the database refuses also undoes the writes before
# it. A subscriber prints every statement that changes the database.
require "active_record"

ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")
ActiveRecord::Schema.verbose = false
ActiveRecord::Schema.define do
  create_table :students do |t|
    t.string :name, null: false
    t.integer :grade, null: false
  end
  create_table :guardians do |t|
    t.references :student, null: false
    t.string :name, null: false
    t.string :phone, null: false, index: { unique: true } # one guardian per mobile
  end
  create_table :fee_plans do |t|
    t.references :student, null: false
    t.string :plan, null: false
    t.integer :total_paise, null: false
  end
end

# Print each write with the values it sends: INSERT INTO guardians name="..."
ActiveSupport::Notifications.subscribe("sql.active_record") do |*, payload|
  sql = payload[:sql]
  next if payload[:name] == "SCHEMA" || sql.start_with?("SELECT", "PRAGMA")
  if (insert = sql.match(/\AINSERT INTO "(\w+)" \(([^)]*)\)/))
    binds = payload[:type_casted_binds]
    binds = binds.call if binds.respond_to?(:call)
    pairs = insert[2].delete('"').split(", ").zip(binds).map { |col, val| "#{col}=#{val.inspect}" }
    puts "  SQL: INSERT INTO #{insert[1]} #{pairs.join(", ")}"
  else
    puts "  SQL: #{sql}"
  end
end

PLAN_PAISE = { "monthly" => 60_000, "term" => 150_000, "year" => 480_000 }.freeze

class Student < ActiveRecord::Base
  validates :name, presence: true
  validates :grade, numericality: { only_integer: true, greater_than_or_equal_to: 1, less_than_or_equal_to: 12 }
end

class Guardian < ActiveRecord::Base
  belongs_to :student
  normalizes :phone, with: ->(value) do
    digits = value.gsub(/\D/, "")
    digits = digits.delete_prefix("0") if digits.length == 11
    digits = digits.delete_prefix("91") if digits.length == 12
    digits.length == 10 ? "+91#{digits}" : digits
  end
  validates :name, presence: true
  validates :phone, format: { with: /\A\+91[6-9]\d{9}\z/, message: "must be an Indian mobile" }
end

class FeePlan < ActiveRecord::Base
  belongs_to :student
end

class EnrolmentForm
  include ActiveModel::API
  include ActiveModel::Attributes

  attribute :student_name, :string
  attribute :student_grade, :integer
  attribute :guardian_name, :string
  attribute :guardian_phone, :string
  attribute :fee_plan, :string, default: "monthly"

  validates :fee_plan, inclusion: { in: PLAN_PAISE.keys }

  def student = @student ||= Student.new(name: student_name, grade: student_grade)
  def guardian = @guardian ||= Guardian.new(student: student, name: guardian_name, phone: guardian_phone)

  def plan
    base = PLAN_PAISE.fetch(fee_plan, 0)
    @plan ||= FeePlan.new(student: student, plan: fee_plan, total_paise: base + base * 18 / 100)
  end

  # 1. Check the form and every record, and copy their messages onto the form.
  # 2. Write all three in one transaction; save! raises if a write is refused.
  # 3. Rescue outside the block, after the ROLLBACK, and answer false.
  def save
    return false unless validate_all

    ActiveRecord::Base.transaction do
      student.save!
      guardian.save!
      plan.save!
    end
    true
  rescue ActiveRecord::RecordNotUnique
    errors.add(:guardian_phone, :taken)
    false
  rescue ActiveRecord::RecordInvalid => e
    errors.add(:base, e.message)
    false
  end

  def validate_all
    valid?
    { student: student, guardian: guardian }.each do |prefix, record|
      next if record.valid?
      record.errors.each { |err| errors.add(:"#{prefix}_#{err.attribute}", err.message) }
    end
    errors.empty?
  end
end

def enrol(label, attrs)
  puts "== #{label} =="
  form = EnrolmentForm.new(attrs)
  ok = form.save
  puts "  save -> #{ok}"
  form.errors.full_messages.each { |m| puts "  - #{m}" }
  puts "  rows: students #{Student.count}, guardians #{Guardian.count}, fee_plans #{FeePlan.count}"
  puts "  student still new? #{form.student.new_record?}" unless ok
  puts
end

enrol("Ravi, term plan",
      student_name: "Ravi Kumar", student_grade: "10",
      guardian_name: "Sita Kumar", guardian_phone: "+91 98765-43210", fee_plan: "term")

enrol("Kiran, same guardian mobile typed another way",
      student_name: "Kiran Kumar", student_grade: "7",
      guardian_name: "Sita Kumar", guardian_phone: "098765 43210", fee_plan: "year")

enrol("A form with a blank name and a grade of 15",
      student_name: "", student_grade: "15",
      guardian_name: "Meera N", guardian_phone: "9876501234", fee_plan: "term")

== Ravi, term plan ==
  SQL: BEGIN immediate TRANSACTION
  SQL: INSERT INTO students name="Ravi Kumar", grade=10
  SQL: INSERT INTO guardians student_id=1, name="Sita Kumar", phone="+919876543210"
  SQL: INSERT INTO fee_plans student_id=1, plan="term", total_paise=177000
  SQL: COMMIT TRANSACTION
  save -> true
  rows: students 1, guardians 1, fee_plans 1

== Kiran, same guardian mobile typed another way ==
  SQL: BEGIN immediate TRANSACTION
  SQL: INSERT INTO students name="Kiran Kumar", grade=7
  SQL: INSERT INTO guardians student_id=2, name="Sita Kumar", phone="+919876543210"
  SQL: ROLLBACK TRANSACTION
  save -> false
  - Guardian phone has already been taken
  rows: students 1, guardians 1, fee_plans 1
  student still new? true

== A form with a blank name and a grade of 15 ==
  save -> false
  - Student name can't be blank
  - Student grade must be less than or equal to 12
  rows: students 1, guardians 1, fee_plans 1
  student still new? true

# The Rails 8.1 markdown response, from a plain Active Model object. The
# NoticesController lists one format, format.md { render markdown: @notice },
# which calls to_markdown on the plain EnrolmentNotice and sends the result
# as text/markdown. Rails 8.1 registers text/markdown as :md itself, so the
# app needs no initializer. A request for JSON finds no branch: 406.
require_relative "session"

Session.serve(
  setup: <<~SH,
    cd ../kaksha
    bin/rails db:prepare 2>&1 | tail -n 2
  SH
  server: "bin/rails server -p 3017 -e development",
  client: <<~SH,
    curl -s -o /dev/null -w "status=%{http_code} content-type=%{content_type} bytes=%{size_download}\\n" -H "Accept: text/markdown" http://localhost:3017/notices/1
    echo "---response body---"
    curl -s -H "Accept: text/markdown" http://localhost:3017/notices/1
    echo "---end body---"
    curl -s -o /dev/null -w "status=%{http_code}\\n" -H "Accept: application/json" http://localhost:3017/notices/1
  SH
  port: 3017,
  folder: "../kaksha",
)

$ cd ../kaksha
$ bin/rails db:prepare 2>&1 | tail -n 2
$ bin/rails server -p 3017 -e development
# The server keeps that terminal. In a second terminal:
$ curl -s -o /dev/null -w "status=%{http_code} content-type=%{content_type} bytes=%{size_download}\n" -H "Accept: text/markdown" http://localhost:3017/notices/1
status=200 content-type=text/markdown; charset=utf-8 bytes=112
$ echo "---response body---"
---response body---
$ curl -s -H "Accept: text/markdown" http://localhost:3017/notices/1
# Enrolment confirmed

Dear Sita Kumar,

Ravi Kumar is enrolled in the term. The fee due is Rs 1770.

-- Kaksha
$ echo "---end body---"
---end body---
$ curl -s -o /dev/null -w "status=%{http_code}\n" -H "Accept: application/json" http://localhost:3017/notices/1
status=406
# Ctrl+C in the first terminal stops the server. That terminal showed:
=> Booting Puma
=> Rails 8.1.4 application starting in development 
=> Run `bin/rails server --help` for more startup options
Puma starting in single mode...
* Puma version: 8.0.2 ("Into the Arena")
* Ruby version: ruby 4.0.7 (2026-09-15 revision 229531a6cf) +PRISM [arm64-darwin23]
*  Min threads: 3
*  Max threads: 3
*  Environment: development
*          PID: …
* Listening on http://127.0.0.1:3017
* Listening on http://[::1]:3017
Use Ctrl-C to stop
Started GET "/notices/1" for ::1 at …
   (…ms)  CREATE TABLE "schema_migrations" ("version" varchar NOT NULL PRIMARY KEY) /*application='Kaksha'*/
   (…ms)  CREATE TABLE "ar_internal_metadata" ("key" varchar NOT NULL PRIMARY KEY, "value" varchar, "created_at" datetime(6) NOT NULL, "updated_at" datetime(6) NOT NULL) /*application='Kaksha'*/
  ActiveRecord::SchemaMigration Load (…ms)  SELECT "schema_migrations"."version" FROM "schema_migrations" ORDER BY "schema_migrations"."version" ASC /*application='Kaksha'*/
Processing by NoticesController#show as MD
  Parameters: {"id" => "1"}
Completed 200 OK in …ms (Views: …ms | ActiveRecord: …ms (0 queries, 0 cached) | GC: …ms)


Started GET "/notices/1" for ::1 at …
Processing by NoticesController#show as MD
  Parameters: {"id" => "1"}
Completed 200 OK in …ms (Views: …ms | ActiveRecord: …ms (0 queries, 0 cached) | GC: …ms)


Started GET "/notices/1" for ::1 at …
Processing by NoticesController#show as JSON
  Parameters: {"id" => "1"}
Completed 406 Not Acceptable in …ms (ActiveRecord: …ms (0 queries, 0 cached) | GC: …ms)


  
ActionController::UnknownFormat (ActionController::UnknownFormat):
  
app/controllers/notices_controller.rb:11:in 'NoticesController#show'
- Gracefully stopping, waiting for requests to finish
=== puma shutdown: … ===
- Goodbye!
Exiting

# Unit tests for the enrolment form object. They load Minitest, Active Model
# (with the Active Support it needs) and the form's own file: no Rails app,
# no server, no browser and no database. Run them with: ruby enrolment_form_test.rb
require "minitest/autorun"
require_relative "enrolment_form"

class EnrolmentFormTest < Minitest::Test
  def form(**changes)
    EnrolmentForm.new({ student_name: "Ravi Kumar", student_grade: "10", guardian_name: "Sita Kumar",
                        guardian_phone: "98765 43210", fee_plan: "term" }.merge(changes))
  end

  def test_a_good_enrolment_is_valid
    assert form.validate_all
  end

  def test_the_phone_is_kept_in_one_shape
    assert_equal "+919876543210", form.guardian.phone
  end

  def test_a_landline_is_cleaned_then_refused
    f = form(guardian_phone: "011 2345 6789")
    refute f.validate_all
    assert_equal ["must be an Indian mobile"], f.errors[:guardian_phone]
  end

  def test_the_student_messages_are_copied_onto_the_form
    f = form(student_name: "", student_grade: "15")
    refute f.validate_all
    assert_equal ["Student name can't be blank", "Student grade must be less than or equal to 12"], f.errors.full_messages
  end

  def test_the_term_fee_is_derived_and_frozen
    fee = form.fee
    assert_equal 177_000, fee.total_paise
    assert fee.frozen?
  end

  def test_nothing_else_of_rails_was_loaded
    refute defined?(ActiveRecord), "Active Record was loaded"
    refute defined?(ActionDispatch), "Action Dispatch was loaded"
  end
end

# Runs the form object's unit tests the way you would in a terminal. The tests
# need Ruby, Minitest and Active Model, and no app, server, browser or database.
require_relative "session"

Session.run(<<~SH)
  cd ..
  ruby enrolment_form_test.rb
SH

$ cd ..
$ ruby enrolment_form_test.rb
Run options: --seed …

# Running:

......

Finished in …s, … runs/s, … assertions/s.

6 runs, 10 assertions, 0 failures, 0 errors, 0 skips