Validations, errors and normalization

# How validations fill the errors object on save, and how to read it.
# Standalone Active Record (no Rails app): an in-memory SQLite database and
# one Student model carrying the usual rules. Nothing here talks to a server.
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
    t.string  :mobile
    t.integer :grade
    t.string  :status,        default: "enquiry"
    t.string  :guardian_name
    t.timestamps
  end
end

class Student < ActiveRecord::Base
  STATUSES = %w[enquiry enrolled left].freeze

  validates :name, presence: true, length: { maximum: 80 }
  validates :mobile,
            format: { with: /\A[6-9]\d{9}\z/, message: "must be a 10-digit Indian mobile" }
  validates :grade, numericality: { only_integer: true, in: 1..12 }
  validates :status, inclusion: { in: STATUSES }
  # Runs only when a record is created, not on later updates.
  validate :guardian_on_create, on: :create

  def guardian_on_create
    errors.add(:guardian_name, :blank, message: "is needed when a student joins") if guardian_name.blank?
  end
end

def show(label, record, context = nil)
  ok = context ? record.valid?(context) : record.valid?
  puts "#{label}: valid?#{context ? "(#{context})" : ""} -> #{ok}"
  record.errors.full_messages.each { |m| puts "  - #{m}" }
end

puts "== A blank new student =="
blank = Student.new
show("new, nothing set", blank)

puts
puts "== Bad values, one per rule =="
bad = Student.new(name: "x" * 90, mobile: "12345", grade: 15, status: "guest", guardian_name: "Asha")
show("too long, bad mobile, bad grade, bad status", bad)

puts
puts "== The error is more than a sentence =="
puts "errors[:mobile]        -> #{bad.errors[:mobile].inspect}"
puts "errors.details[:grade] -> #{bad.errors.details[:grade].inspect}"
puts "the :grade symbol is what the i18n layer turns into a message"

puts
puts "== save returns false and writes no row =="
saved = bad.save
puts "bad.save -> #{saved}; rows in students: #{Student.count}"

puts
puts "== Context decides which rules run =="
ok = Student.create!(name: "Ravi Kumar", mobile: "9876543210", grade: 10, guardian_name: "Sita Kumar")
puts "created id=#{ok.id}, rows: #{Student.count}"
ok.guardian_name = ""
puts "update without guardian -> valid? #{ok.valid?} (default context: the create-only rule is skipped)"
puts "valid?(:create)         -> #{ok.valid?(:create)} (the create-only rule runs again)"
ok.errors.full_messages.each { |m| puts "  - #{m}" }

== A blank new student ==
new, nothing set: valid? -> false
  - Name can't be blank
  - Mobile must be a 10-digit Indian mobile
  - Grade is not a number
  - Guardian name is needed when a student joins

== Bad values, one per rule ==
too long, bad mobile, bad grade, bad status: valid? -> false
  - Name is too long (maximum is 80 characters)
  - Mobile must be a 10-digit Indian mobile
  - Grade must be in 1..12
  - Status is not included in the list

== The error is more than a sentence ==
errors[:mobile]        -> ["must be a 10-digit Indian mobile"]
errors.details[:grade] -> [{error: :in, value: 15, count: 1..12}]
the :grade symbol is what the i18n layer turns into a message

== save returns false and writes no row ==
bad.save -> false; rows in students: 0

== Context decides which rules run ==
created id=1, rows: 1
update without guardian -> valid? true (default context: the create-only rule is skipped)
valid?(:create)         -> false (the create-only rule runs again)
  - Guardian name is needed when a student joins

# normalizes runs on assignment and also when a value is used to query, so a
# phone number is stored and looked up in one canonical shape. Standalone
# Active Record with an in-memory SQLite database; no server, no network.
require "active_record"

ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")

ActiveRecord::Schema.verbose = false
ActiveRecord::Schema.define do
  create_table :guardians do |t|
    t.string :name
    t.string :phone
    t.timestamps
  end
  add_index :guardians, :phone, unique: true
end

class Guardian < ActiveRecord::Base
  # Keep digits only, drop a leading 0 or 91, then store as +91 and ten digits.
  normalizes :phone, with: ->(value) do
    digits = value.to_s.gsub(/\D/, "")
    digits = digits.delete_prefix("0")
    digits = digits.delete_prefix("91") if digits.length == 12
    "+91#{digits}"
  end

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

puts "== One number entered four ways, stored once =="
["+91 98765-43210", "098765 43210", "919876543210", "9876543210"].each do |typed|
  g = Guardian.new(phone: typed)
  printf "  typed %-18s stored %s\n", typed.inspect, g.phone.inspect
end

g = Guardian.create!(name: "Sita Kumar", phone: "+91 98765-43210")
puts "\nsaved id=#{g.id}, phone=#{g.phone.inspect}"

puts "\n== Looked up three ways, each query normalized first =="
[
  '98765 43210',
  '0 98765 43210',
  '+91-98765-43210',
].each do |typed|
  found = Guardian.find_by(phone: typed)
  puts "  find_by(phone: #{typed.inspect}) -> #{found&.name.inspect}"
end

puts "\n== A number that is not a mobile is refused =="
bad = Guardian.new(name: "Front desk", phone: "011 2345 6789")
puts "  phone stored as #{bad.phone.inspect}; valid? #{bad.valid?}"
bad.errors.full_messages.each { |m| puts "  - #{m}" }

== One number entered four ways, stored once ==
  typed "+91 98765-43210"  stored "+919876543210"
  typed "098765 43210"     stored "+919876543210"
  typed "919876543210"     stored "+919876543210"
  typed "9876543210"       stored "+919876543210"

saved id=1, phone="+919876543210"

== Looked up three ways, each query normalized first ==
  find_by(phone: "98765 43210") -> "Sita Kumar"
  find_by(phone: "0 98765 43210") -> "Sita Kumar"
  find_by(phone: "+91-98765-43210") -> "Sita Kumar"

== A number that is not a mobile is refused ==
  phone stored as "+911123456789"; valid? false
  - Phone must be an Indian mobile

# The uniqueness validation is a SELECT that runs just before the INSERT, so
# two requests that arrive together can both pass it. Only a unique index in
# the database can refuse the second INSERT. This shows both halves.
#
# To keep the run repeatable, the two requests validate first, in their own
# threads, against the empty table (both pass), then each runs its INSERT.
# That is the order a real race produces: every request checked, found nothing,
# and went on to insert.
require "active_record"

DB = "uniqueness_race.sqlite3"
File.delete(DB) if File.exist?(DB)
ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: DB, pool: 5)

ActiveRecord::Schema.verbose = false
ActiveRecord::Schema.define do
  create_table :enrollments do |t|
    t.integer :student_id, null: false
    t.integer :batch_id,   null: false
    t.timestamps
  end
  # The index that makes the duplicate impossible, whatever the timing.
  add_index :enrollments, [:student_id, :batch_id], unique: true, name: "idx_one_seat"
end

class Enrollment < ActiveRecord::Base
  validates :student_id, uniqueness: { scope: :batch_id, message: "is already enrolled in this batch" }
end

puts "== Two requests, same student (41) and batch (7), validate at once =="
pair = %w[request-A request-B].map do |label|
  Thread.new do
    ActiveRecord::Base.connection_pool.with_connection do
      e = Enrollment.new(student_id: 41, batch_id: 7)
      [label, e, e.valid?] # the uniqueness SELECT finds no row yet
    end
  end
end.map(&:value)

pair.each { |label, _e, valid| puts "  #{label}: valid? -> #{valid} (the SELECT found no existing seat)" }

puts "\n== Each request now runs its INSERT (validation already passed) =="
pair.each do |label, e, _valid|
  e.save!(validate: false)
  puts "  #{label}: INSERT ok, id=#{e.id}"
rescue ActiveRecord::RecordNotUnique => error
  first = error.message.split("\n").first
  puts "  #{label}: INSERT refused by the index -> #{first}"
end
puts "  rows in enrollments: #{Enrollment.count} (the index kept it at one)"

puts "\n== Without the index, the validation alone lets the duplicate through =="
ActiveRecord::Schema.define do
  create_table :wishes do |t|
    t.integer :student_id, null: false
    t.integer :batch_id,   null: false
  end
end
class Wish < ActiveRecord::Base
  validates :student_id, uniqueness: { scope: :batch_id }
end
two = %w[request-A request-B].map do |label|
  Thread.new do
    ActiveRecord::Base.connection_pool.with_connection do
      w = Wish.new(student_id: 41, batch_id: 7)
      [label, w, w.valid?]
    end
  end
end.map(&:value)
two.each { |_label, w, _valid| w.save!(validate: false) }
puts "  both validations passed: #{two.map { |_l, _w, v| v }.inspect}; rows in wishes: #{Wish.count} (a duplicate)"

ActiveRecord::Base.connection_pool.disconnect!
File.delete(DB) if File.exist?(DB)

== Two requests, same student (41) and batch (7), validate at once ==
  request-A: valid? -> true (the SELECT found no existing seat)
  request-B: valid? -> true (the SELECT found no existing seat)

== Each request now runs its INSERT (validation already passed) ==
  request-A: INSERT ok, id=1
  request-B: INSERT refused by the index -> SQLite3::ConstraintException: UNIQUE constraint failed: enrollments.student_id, enrollments.batch_id
  rows in enrollments: 1 (the index kept it at one)

== Without the index, the validation alone lets the duplicate through ==
  both validations passed: [true, true]; rows in wishes: 2 (a duplicate)

# Two ways to write a rule Rails has no built-in for, and how if:/unless: keep
# a rule from running when it should not apply. Standalone Active Record.
require "active_record"

ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")

ActiveRecord::Schema.verbose = false
ActiveRecord::Schema.define do
  create_table :guardians do |t|
    t.string  :name
    t.string  :relation
    t.string  :pin_code
    t.boolean :primary_contact, default: false
    t.string  :phone
  end
end

# An allowlist: only these relations are accepted. Anything else is rejected,
# which is safer than trying to list every value to reject.
RELATIONS = %w[mother father guardian grandparent sibling].freeze

# A reusable validator class: Rails calls validate for each record.
class PinCodeValidator < ActiveModel::Validator
  def validate(record)
    pin = record.pin_code.to_s
    return if pin.match?(/\A[1-9]\d{5}\z/)

    record.errors.add(:pin_code, :invalid, message: "must be 6 digits and not start with 0")
  end
end

class Guardian < ActiveRecord::Base
  validates_with PinCodeValidator
  validates :relation, inclusion: { in: RELATIONS, message: "is not a relation we accept" }

  # A method validator: a primary contact must have a phone, others need not.
  validate :primary_contact_has_phone

  # A conditional rule: only check the phone shape when one was given.
  validates :phone,
            format: { with: /\A\+91[6-9]\d{9}\z/, message: "must be an Indian mobile" },
            unless: -> { phone.blank? }

  def primary_contact_has_phone
    return unless primary_contact?

    errors.add(:phone, :blank, message: "is needed for the primary contact") if phone.blank?
  end
end

def report(label, g)
  puts "#{label}: valid? -> #{g.valid?}"
  g.errors.full_messages.each { |m| puts "  - #{m}" }
end

puts "== The allowlist rejects a relation it does not know =="
report("relation 'uncle'", Guardian.new(name: "Raj", relation: "uncle", pin_code: "560001"))

puts "\n== The validator class checks the PIN code =="
report("pin_code '0560'", Guardian.new(name: "Raj", relation: "father", pin_code: "0560"))

puts "\n== unless: skips the phone rule when no phone was given =="
report("no phone, not primary", Guardian.new(name: "Raj", relation: "father", pin_code: "560001"))

puts "\n== but a primary contact must have one =="
report("primary, no phone", Guardian.new(name: "Raj", relation: "father", pin_code: "560001", primary_contact: true))

puts "\n== a well-formed guardian passes every rule =="
report("all good", Guardian.new(name: "Sita", relation: "mother", pin_code: "560001", primary_contact: true, phone: "+919876543210"))

== The allowlist rejects a relation it does not know ==
relation 'uncle': valid? -> false
  - Relation is not a relation we accept

== The validator class checks the PIN code ==
pin_code '0560': valid? -> false
  - Pin code must be 6 digits and not start with 0

== unless: skips the phone rule when no phone was given ==
no phone, not primary: valid? -> true

== but a primary contact must have one ==
primary, no phone: valid? -> false
  - Phone is needed for the primary contact

== a well-formed guardian passes every rule ==
all good: valid? -> true

# enum with validate: true turns an unknown value into a validation error you
# can show, instead of the ArgumentError a plain enum raises on assignment.
# Standalone Active Record, in-memory SQLite, no server.
require "active_record"

ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")

ActiveRecord::Schema.verbose = false
ActiveRecord::Schema.define do
  create_table :enquiries do |t|
    t.string :name
    t.string :stage, default: "open"
  end
  create_table :leads do |t|
    t.string :name
    t.string :stage, default: "open"
  end
end

STAGES = { open: "open", contacted: "contacted", joined: "joined", lost: "lost" }.freeze

class Enquiry < ActiveRecord::Base
  # A plain enum: an unknown value raises on assignment.
  enum :stage, STAGES
end

class Lead < ActiveRecord::Base
  # validate: true: an unknown value becomes a normal validation error.
  enum :stage, STAGES, validate: true
end

puts "== A plain enum raises on an unknown value =="
begin
  Enquiry.new(stage: "prospect")
rescue ArgumentError => e
  puts "  Enquiry.new(stage: \"prospect\") raised ArgumentError"
  puts "  -> #{e.message}"
end

puts "\n== With validate: true the unknown value is held and reported =="
lead = Lead.new(name: "Meena", stage: "prospect")
puts "  Lead.new(stage: \"prospect\") did not raise"
puts "  lead.stage     -> #{lead.stage.inspect}"
puts "  lead.valid?    -> #{lead.valid?}"
lead.errors.full_messages.each { |m| puts "  - #{m}" }

puts "\n== A known value still works, and the predicates come with it =="
good = Lead.new(name: "Arjun", stage: "contacted")
puts "  good.valid?     -> #{good.valid?}"
puts "  good.contacted? -> #{good.contacted?}"
puts "  Lead.stages     -> #{Lead.stages.inspect}"

== A plain enum raises on an unknown value ==
  Enquiry.new(stage: "prospect") raised ArgumentError
  -> 'prospect' is not a valid stage

== With validate: true the unknown value is held and reported ==
  Lead.new(stage: "prospect") did not raise
  lead.stage     -> "prospect"
  lead.valid?    -> false
  - Stage is not included in the list

== A known value still works, and the predicates come with it ==
  good.valid?     -> true
  good.contacted? -> true
  Lead.stages     -> {"open" => "open", "contacted" => "contacted", "joined" => "joined", "lost" => "lost"}