Application Architecture in Plain Ruby

# frozen_string_literal: true

require "shelf"

module Shelf
  # A fine in cents: immutable, comparable, and usable as a Hash key.
  Fine = Data.define(:cents) do
    include Comparable

    def initialize(cents: 0)
      valid = cents.is_a?(Integer) && !cents.negative?
      raise ArgumentError, "cents must be a non-negative Integer, got #{cents.inspect}" unless valid

      super
    end

    def <=>(other) = other.is_a?(Fine) ? cents <=> other.cents : nil

    def +(other) = with(cents: cents + other.cents)

    def zero? = cents.zero?

    def to_s = format("%<euros>d.%<rest>02d EUR", euros: cents / 100, rest: cents % 100)
  end
end

a = Shelf::Fine.new(250)
b = Shelf::Fine.new(cents: 75)
total = a + b # => #<data Shelf::Fine cents=325>
total.to_s                                    # => "3.25 EUR"
[a, b].min                                    # => #<data Shelf::Fine cents=75>
a.between?(b, Shelf::Fine.new(1000))          # => true
Shelf::Fine.new                               # => #<data Shelf::Fine cents=0>
{ a => :open }[Shelf::Fine.new(250)]          # => :open
a.frozen?                                     # => true

begin
  Shelf::Fine.new(-1)
rescue ArgumentError => e
  e.message # => "cents must be a non-negative Integer, got -1"
end

begin
  a < 5
rescue ArgumentError => e
  e.message # => "comparison of Shelf::Fine with 5 failed"
end

begin
  a.instance_variable_set(:@cents, 1)
rescue FrozenError => e
  e.message # => "can't modify frozen Shelf::Fine: #<data Shelf::Fine cents=250>"
end

# frozen_string_literal: true

require "shelf"

module Shelf
  module Loans
    # Infrastructure: where lent ISBNs are remembered.
    class Memory
      def initialize = @lent = {}

      def lent?(isbn) = @lent.key?(isbn)

      def add(isbn, due_at) = @lent[isbn] = due_at

      def due_at(isbn) = @lent.fetch(isbn)
    end
  end

  # Application layer: one use case, one callable object.
  class LendBook
    Success = Data.define(:book, :due_at)
    Failure = Data.define(:reason)

    def self.call(...) = new(...).call

    def initialize(catalog:, isbn:, loans: Loans::Memory.new, clock: -> { Time.now }, loan_days: Shelf.config.loan_days)
      @catalog = catalog
      @isbn = isbn
      @loans = loans
      @clock = clock
      @loan_days = loan_days
    end

    def call
      book = @catalog.find { |b| b.isbn == @isbn }
      return Failure.new(reason: :unknown_isbn) unless book
      return Failure.new(reason: :already_lent) if @loans.lent?(@isbn)

      due_at = @clock.call + (@loan_days * 86_400)
      @loans.add(@isbn, due_at)
      Success.new(book:, due_at:)
    end
  end
end

isbn = Shelf::Isbn.new("978-0-306-40615-7")
catalog = Shelf::Catalog.new.add(Shelf::Book.new(isbn, "The Dispossessed", Shelf::Author.new("Ursula K. Le Guin")))
loans = Shelf::Loans::Memory.new
clock = -> { Time.utc(2026, 10, 18, 9, 0) }

def report(result)
  case result
  in Shelf::LendBook::Success(book:, due_at:)
    "lent #{book.title} until #{due_at.strftime('%Y-%m-%d')}"
  in Shelf::LendBook::Failure(reason: :already_lent)
    "sorry, already lent"
  in Shelf::LendBook::Failure(reason:)
    "failed: #{reason}"
  end
end

report(Shelf::LendBook.call(catalog:, isbn:, loans:, clock:)) # => "lent The Dispossessed until 2026-11-01"
report(Shelf::LendBook.call(catalog:, isbn:, loans:, clock:)) # => "sorry, already lent"
report(Shelf::LendBook.call(catalog:, isbn: Shelf::Isbn.new("978-1-4028-9462-6"), loans:)) # => "failed: unknown_isbn"

begin
  Shelf::LendBook.call(catalog:)
rescue ArgumentError => e
  e.message # => "missing keyword: :isbn"
end

# frozen_string_literal: true

require "shelf"

module Shelf
  # A callable object: the one public method is #call, so it composes like a lambda.
  class Slug
    def self.call(...) = new.call(...)

    def call(title) = title.downcase.gsub(/[^a-z0-9]+/, "-").delete_prefix("-").delete_suffix("-")

    alias to_slug call

    def to_proc = method(:call).to_proc
  end
end

Shelf::Slug.call("The Dispossessed!") # => "the-dispossessed"
Shelf::Slug.new.call("A Wizard of Earthsea") # => "a-wizard-of-earthsea"
Shelf::Slug.new.to_slug("Dracula") # => "dracula"
%w[Dune Kindred].map(&Shelf::Slug.new) # => ["dune", "kindred"]

pipeline = :strip.to_proc >> Shelf::Slug.new >> ->(slug) { "/books/#{slug}" }
pipeline.call("  The Left Hand of Darkness ")     # => "/books/the-left-hand-of-darkness"
pipeline.lambda?                                  # => true

# frozen_string_literal: true

require "shelf"

module Shelf
  # Filter object: turns raw, untrusted parameters into a small immutable value.
  SearchFilter = Data.define(:title, :author) do
    def self.parse(params)
      new(title: clean(params[:title]), author: clean(params[:author]))
    end

    def self.clean(value) = value.to_s.strip.then { it.empty? ? nil : it.downcase }
    private_class_method :clean

    def keep?(book)
      (title.nil? || book.title.downcase.include?(title)) &&
        (author.nil? || book.author.name.downcase.include?(author))
    end
  end

  # Query object: one question asked of the catalogue, returning a lazy enumerator.
  class BooksMatching
    def initialize(catalog) = @catalog = catalog

    def call(filter) = @catalog.lazy.select { filter.keep?(it) }
  end

  # Form object: validates input and only then builds domain objects.
  class NewBookForm
    attr_reader :errors

    def initialize(isbn:, title:, author:)
      @isbn = isbn
      @title = title
      @author = author
      @errors = {}
    end

    def valid?
      @errors = {}
      @errors[:title] = "can't be blank" if @title.to_s.strip.empty?
      @errors[:author] = "can't be blank" if @author.to_s.strip.empty?
      @errors[:isbn] = "is not a valid ISBN-13" unless isbn
      @errors.empty?
    end

    def to_book
      raise Shelf::Error, "form is invalid: #{errors.keys.join(', ')}" unless valid?

      Book.new(isbn, @title.strip, Author.new(@author.strip))
    end

    private

    def isbn
      Isbn.new(@isbn)
    rescue ArgumentError
      nil
    end
  end

  # Policy object: a decision plus its reason, with no side effects.
  class LendingPolicy
    Decision = Data.define(:allowed, :reason)

    def initialize(max_loans: 3) = @max_loans = max_loans

    def call(fine_cents:, active_loans:)
      return Decision.new(false, "too many loans") if active_loans >= @max_loans

      case fine_cents
      when ...500 then Decision.new(true, nil)
      when 500...2000 then Decision.new(true, "pay your fines soon")
      else Decision.new(false, "fines of #{fine_cents} cents are due")
      end
    end
  end
end

catalog = Shelf::Catalog.new
[["978-0-306-40615-7", "The Dispossessed", "Ursula K. Le Guin"],
 ["978-1-4028-9462-6", "A Wizard of Earthsea", "Ursula K. Le Guin"],
 ["978-0-14-143951-8", "Dracula", "Bram Stoker"]].each do |isbn, title, author|
  catalog.add(Shelf::NewBookForm.new(isbn:, title:, author:).to_book)
end

filter = Shelf::SearchFilter.parse({ title: "  ", author: "LE GUIN " })
filter.to_h # => {title: nil, author: "le guin"}
Shelf::BooksMatching.new(catalog).call(filter).map(&:title).to_a # => ["The Dispossessed", "A Wizard of Earthsea"]

form = Shelf::NewBookForm.new(isbn: "978-0-306-40615-8", title: " ", author: "Ana")
form.valid? # => false
form.errors # => {title: "can't be blank", isbn: "is not a valid ISBN-13"}

policy = Shelf::LendingPolicy.new
policy.call(fine_cents: 100, active_loans: 1) # => #<data Shelf::LendingPolicy::Decision allowed=true, reason=nil>
policy.call(fine_cents: 750, active_loans: 1).reason # => "pay your fines soon"
policy.call(fine_cents: 5000, active_loans: 1).reason # => "fines of 5000 cents are due"
policy.call(fine_cents: 0, active_loans: 3).allowed # => false

# frozen_string_literal: true

require "delegate"
require "shelf"

module Shelf
  module Store
    # The port: what the application layer expects of any store.
    class Base
      @registry = {}

      class << self
        attr_reader :registry

        # Every named subclass registers itself under its lower-cased class name.
        def inherited(subclass)
          super
          Base.registry[subclass.name.split("::").last.downcase.to_sym] = subclass if subclass.name
        end

        def build(name, ...)
          Base.registry.fetch(name) { raise Shelf::Error, "unknown store: #{name.inspect}" }.new(...)
        end
      end

      def all = raise(NoMethodError, "#{self.class} must implement #all")

      def add(_book) = raise(NoMethodError, "#{self.class} must implement #add")
    end

    # An adapter around a vendor client with a different vocabulary.
    class Legacy < Base
      def initialize(client)
        super()
        @client = client
      end

      def all = @client.fetch_rows.map { |isbn, title, author| Book.new(Isbn.new(isbn), title, Author.new(author)) }

      def add(book)
        @client.insert_row([book.isbn.digits, book.title, book.author.name])
        self
      end
    end

    # A decorator that adds behaviour to any store without changing its interface.
    class Counting < SimpleDelegator
      attr_reader :reads

      def initialize(store)
        super
        @reads = 0
      end

      def all
        @reads += 1
        super
      end
    end
  end
end

# A stand-in for a third-party client with its own vocabulary.
LegacyClient = Struct.new(:rows) do
  def fetch_rows = rows.dup

  def insert_row(row) = rows << row
end

book = Shelf::Book.new(Shelf::Isbn.new("978-0-306-40615-7"), "The Dispossessed", Shelf::Author.new("Ursula K. Le Guin"))

legacy = Shelf::Store::Base.build(:legacy, LegacyClient.new([]))
store = Shelf::Store::Counting.new(legacy)
catalog = Shelf::Catalog.new(store:).add(book)

catalog.map(&:to_s)  # => ["The Dispossessed by Ursula K. Le Guin"]
store.reads          # => 1
Shelf::Store::Base.registry.keys # => [:legacy]

begin
  Shelf::Store::Base.build(:redis)
rescue Shelf::Error => e
  e.message # => "unknown store: :redis"
end

begin
  Incomplete = Class.new(Shelf::Store::Base) # rubocop:disable Style/EmptyClassDefinition
  Incomplete.new.all
rescue NoMethodError => e
  e.message # => "Incomplete must implement #all"
end

Shelf::Store::Base.registry.keys # => [:legacy]

module Shelf
  # What the application layer expects of any store.
  interface _Store
    def all: () -> Array[Book]
    def add: (Book book) -> self
  end

  class Catalog
    include Enumerable[Book]

    def initialize: (?store: _Store) -> void
  end
end

# frozen_string_literal: true

require "shelf"
require "shelf/lend_book"

isbn = Shelf::Isbn.new("978-0-306-40615-7")
book = Shelf::Book.new(isbn, "The Dispossessed", Shelf::Author.new("Ursula K. Le Guin"))
catalog = Shelf::Catalog.new.add(book)
shared = Shelf::Loans::Memory.new

# 1. A quick script relies on the defaults: a fresh repository and the system clock.
Shelf::LendBook.call(catalog:, isbn:).class # => Shelf::LendBook::Success
Shelf::LendBook.call(catalog:, isbn:).class # => Shelf::LendBook::Success

# 2. The application passes the one shared repository: the second call is refused.
Shelf::LendBook.call(catalog:, isbn:, loans: shared).class # => Shelf::LendBook::Success
Shelf::LendBook.call(catalog:, isbn:, loans: shared).class # => Shelf::LendBook::Failure

# 3. A test replaces the clock and the number of days.
result = Shelf::LendBook.call(catalog:, isbn:, clock: -> { Time.utc(2026, 1, 1) }, loan_days: 1)
result.due_at.iso8601 # => "2026-01-02T00:00:00Z"

# frozen_string_literal: true

require "delegate"
require "json"
require "shelf"

module Shelf
  # Open presenter: a decorator that forwards everything it does not override.
  class BookPresenter < SimpleDelegator
    def label = "#{title} (#{author.name})"

    def isbn_with_hyphens = isbn.digits.sub(/\A(\d{3})(\d)(\d{3})(\d{5})(\d)\z/, '\1-\2-\3-\4-\5')
  end

  # Closed presenter: exposes exactly what the view needs and nothing else.
  class BookCard
    def initialize(book) = @book = book

    def title = @book.title

    def author = @book.author.name
  end

  # Serializer: domain object in, plain Hash out. No JSON dependency here.
  class BookSerializer
    def initialize(book) = @book = book

    def as_json = { isbn: @book.isbn.digits, title: @book.title, author: @book.author.name }
  end

  # Boundary parser: untrusted JSON in, domain object out.
  module BookParser
    def self.call(json)
      case JSON.parse(json, symbolize_names: true)
      in { isbn: String => isbn, title: String => title, author: { name: String => name } }
        Book.new(Isbn.new(isbn), title, Author.new(name))
      end
    end
  end
end

book = Shelf::Book.new(Shelf::Isbn.new("978-0-306-40615-7"), "The Dispossessed", Shelf::Author.new("Ursula K. Le Guin"))

presenter = Shelf::BookPresenter.new(book)
presenter.label                # => "The Dispossessed (Ursula K. Le Guin)"
presenter.isbn_with_hyphens    # => "978-0-306-40615-7"
presenter.title                # => "The Dispossessed"
presenter.eql?(book)           # => true
book.eql?(presenter)           # => false
presenter.is_a?(Shelf::Book)   # => false
presenter.__getobj__.equal?(book) # => true

card = Shelf::BookCard.new(book)
card.respond_to?(:isbn) # => false

serializer = Shelf::BookSerializer.new(book)
serializer.as_json # => {isbn: "9780306406157", title: "The Dispossessed", author: "Ursula K. Le Guin"}
JSON.generate(serializer.as_json).start_with?('{"isbn":"9780306406157"') # => true

wire = '{"isbn":"978-0-306-40615-7","title":"The Dispossessed","author":{"name":"Ursula K. Le Guin"}}'
Shelf::BookParser.call(wire).eql?(book) # => true

begin
  Shelf::BookParser.call('{"title":"No ISBN"}')
rescue NoMatchingPatternKeyError => e
  e.message # => "{title: \"No ISBN\"}: key not found: :isbn"
end

# frozen_string_literal: true

require "shelf"

module Shelf
  # Per-request context: explicit, resettable, and isolated per fiber.
  module Current
    KEY = :shelf_member

    def self.member = Fiber[KEY]

    def self.with(member)
      previous = Fiber[KEY]
      Fiber[KEY] = member
      yield
    ensure
      Fiber[KEY] = previous
    end
  end
end

Shelf::Current.member # => nil

Shelf::Current.with("ana") do
  Shelf::Current.member                                 # => "ana"
  Fiber.new { Shelf::Current.member }.resume            # => "ana"
  Thread.new { Shelf::Current.member }.value            # => "ana"
  Fiber.new { Shelf::Current.with("ben") { Shelf::Current.member } }.resume # => "ben"
  Shelf::Current.member # => "ana"
end

Shelf::Current.member # => nil

# The older, fiber-local hash behind Thread#[]: not inherited by new fibers.
Thread.current[:request_id] = 42
Thread.current[:request_id]                             # => 42
Fiber.new { Thread.current[:request_id] }.resume        # => nil

# Thread variables are shared by every fiber of the thread.
Thread.current.thread_variable_set(:locale, :es)
Fiber.new { Thread.current.thread_variable_get(:locale) }.resume # => :es
Thread.new { Thread.current.thread_variable_get(:locale) }.value # => nil

# frozen_string_literal: true

require "shelf"
require "yaml"

module Shelf
  # Configuration object: built once at the edge, validated, frozen, and passed in.
  Settings = Data.define(:store, :loan_days, :base_url, :on_overdue) do
    # Any object with #fetch works: ENV in production, a Hash in tests.
    def self.from_env(env = ENV)
      new(
        store: env.fetch("SHELF_STORE", "memory").to_sym,
        loan_days: Integer(env.fetch("SHELF_LOAN_DAYS", "14")),
        base_url: env.fetch("SHELF_BASE_URL"),
        on_overdue: ->(loan) { warn "overdue: #{loan}" }
      )
    end

    def initialize(store:, loan_days:, base_url:, on_overdue: nil)
      raise ArgumentError, "loan_days must be positive" unless loan_days.positive?

      super(store:, loan_days:, base_url: base_url.delete_suffix("/"), on_overdue: on_overdue || ->(_loan) {})
    end
  end
end

env = { "SHELF_BASE_URL" => "https://library.example/", "SHELF_LOAN_DAYS" => "21" }
settings = Shelf::Settings.from_env(env)
settings.to_h.except(:on_overdue) # => {store: :memory, loan_days: 21, base_url: "https://library.example"}
settings.frozen?                  # => true
settings.on_overdue.call("Dune")  # => nil

begin
  Shelf::Settings.from_env({})
rescue KeyError => e
  e.message # => "key not found: \"SHELF_BASE_URL\""
end

begin
  Shelf::Settings.from_env(env.merge("SHELF_LOAN_DAYS" => "two weeks"))
rescue ArgumentError => e
  e.message # => "invalid value for Integer(): \"two weeks\""
end

# Per-environment files with YAML anchors, loaded safely (aliases must be allowed explicitly).
yaml = <<~YAML
  default: &default
    loan_days: 14
    store: memory
  production:
    <<: *default
    loan_days: 28
YAML

YAML.safe_load(yaml, aliases: true, symbolize_names: true).fetch(:production) # => {loan_days: 28, store: "memory"}

begin
  YAML.safe_load(yaml)
rescue Psych::AliasesNotEnabled => e
  e.message # => "Alias parsing was not enabled. To enable it, pass `aliases: true` to `Psych::load` or `Psych::safe_load`."
end

# frozen_string_literal: true

require "shelf"
require "shelf/lend_book"
require "shelf/settings"

module Shelf
  # Composition root: the one place that knows every concrete class.
  class Application
    STORES = { memory: Store::Memory }.freeze

    attr_reader :catalog

    def initialize(settings, clock: -> { Time.now })
      @settings = settings
      @catalog = Catalog.new(store: STORES.fetch(settings.store).new)
      @loans = Loans::Memory.new
      @clock = clock
    end

    def lend(isbn)
      LendBook.call(catalog:, isbn:, loans: @loans, clock: @clock, loan_days: @settings.loan_days)
    end
  end
end

settings = Shelf::Settings.from_env({ "SHELF_BASE_URL" => "https://library.example", "SHELF_LOAN_DAYS" => "7" })
app = Shelf::Application.new(settings, clock: -> { Time.utc(2026, 10, 18) })

isbn = Shelf::Isbn.new("978-0-306-40615-7")
app.catalog.add(Shelf::Book.new(isbn, "The Dispossessed", Shelf::Author.new("Ursula K. Le Guin")))

app.lend(isbn).due_at.iso8601 # => "2026-10-25T00:00:00Z"
app.lend(isbn).reason         # => :already_lent

# frozen_string_literal: true

require "minitest/autorun"
require "shelf"
require "shelf/lend_book"

class LendBookTest < Minitest::Test
  # A hand-written fake: any object with #lent? and #add can stand in for the real repository.
  class FakeLoans
    attr_reader :added

    def initialize(lent: [])
      @lent = lent
      @added = []
    end

    def lent?(isbn) = @lent.include?(isbn)

    def add(isbn, due_at) = @added << [isbn, due_at]
  end

  def setup
    @isbn = Shelf::Isbn.new("978-0-306-40615-7")
    book = Shelf::Book.new(@isbn, "The Dispossessed", Shelf::Author.new("Ursula K. Le Guin"))
    @catalog = Shelf::Catalog.new(store: Shelf::Store::Memory.new).add(book)
    @clock = -> { Time.utc(2026, 10, 18) }
  end

  def test_lends_for_the_configured_number_of_days
    loans = FakeLoans.new
    result = Shelf::LendBook.call(catalog: @catalog, isbn: @isbn, loans:, clock: @clock, loan_days: 3)

    assert_equal Time.utc(2026, 10, 21), result.due_at
    assert_equal [[@isbn, Time.utc(2026, 10, 21)]], loans.added
  end

  def test_refuses_a_book_that_is_already_lent
    loans = FakeLoans.new(lent: [@isbn])
    result = Shelf::LendBook.call(catalog: @catalog, isbn: @isbn, loans:)

    assert_equal :already_lent, result.reason
    assert_empty loans.added
  end
end

2 runs, 5 assertions, 0 failures, 0 errors, 0 skips