command_model 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e62322d3750507b2218d0e2662517d807c4207a5f225ee98ab9eda6d39a9206
-  data.tar.gz: 5350099e5f9e77a68441faf7fab88fdcc736c36a0d1ac9dbd9d48ca75785cf14
+  metadata.gz: ae545ab3c7c527111971b821772770a8b050f897550fa3512c6476edd67182d1
+  data.tar.gz: be5789d54e5e90730445343e9d29bd789c6a3f5f42e34a5f78075996ae51d929
 SHA512:
-  metadata.gz: 2aede9435d4d3a0dc779101807f02def57e15764b352d2228a89aa91fc341c098fcf17919f85ec2a9e222a97535b0c9e2a540dc2a104de72262d3f875e1b65c0
-  data.tar.gz: 7a01b95bf05e04b86c4735d21b1dae876e34dc4de3f1e6117c166dbeb46c191d7f05df10889791ad60be0355134edd2866598c02d80962984afdeab8891056b9
+  metadata.gz: 02613c5fed0d0518ac3bff0a2d7b0fc77974d323693e1f18068d767c28bc4cc7521bb7fdece9a49ef5ef8c82a4213c098edb61972a391cb6b2be90570efc349c
+  data.tar.gz: d683d0d3823c268784c1821c9defed0f68fb3cc7c5cda98440d2676bae7845d8b2e6aa94de6f5ce3665b9235f7bd25efe1ec51b312342441efec370feb9d2ea9

data/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: "Ruby CI"
+on:
+  push:
+    branches: ["master"]
+  pull_request:
+    branches: ["master"]
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ['3.2', '3.3']
+        gemfile: [ "6.1", "7.0", "7.1" ]
+    runs-on: ubuntu-latest
+    env:
+      BUNDLE_GEMFILE: ${{ github.workspace }}/gemfiles/${{ matrix.gemfile }}.gemfile
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Install Ruby and gems
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+      - name: Run tests
+        run: bin/rake

data/.gitignore

@@ -3,7 +3,6 @@
 .bundle
 .config
 .yardoc
-Gemfile.lock
 InstalledFiles
 _yardoc
 coverage
@@ -15,3 +14,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+.envrc

data/.ruby-version

@@ -0,0 +1 @@
+3.2.2

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.2.2

data/Gemfile.lock

@@ -0,0 +1,50 @@
+PATH
+  remote: .
+  specs:
+    command_model (2.1.0)
+      activemodel (> 6.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (7.0.4.3)
+      activesupport (= 7.0.4.3)
+    activesupport (7.0.4.3)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+    concurrent-ruby (1.2.2)
+    diff-lcs (1.5.1)
+    i18n (1.12.0)
+      concurrent-ruby (~> 1.0)
+    minitest (5.18.0)
+    rake (13.1.0)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.0)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.1)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+
+PLATFORMS
+  arm64-darwin-22
+  arm64-darwin-23
+  x86_64-linux
+
+DEPENDENCIES
+  command_model!
+  rake (~> 13.1.0)
+  rspec (~> 3.13.0)
+
+BUNDLED WITH
+   2.4.3

data/README.md

@@ -1,4 +1,4 @@
-[![Build Status](https://travis-ci.org/jackc/command_model.svg)](https://travis-ci.org/jackc/command_model)
+[![Build Status](https://github.com/jackc/command_model/actions/workflows/ci.yml/badge.svg)](https://github.com/jackc/command_model/actions/workflows/ci.yml)
 
 # CommandModel
 
@@ -14,11 +14,13 @@ to work with once your domain operations become more complex. Domain models
 usually have richer behavior than can be represented with a typical
 ActiveRecord style update_attributes.
 
-    # yuck!
-    account.update_attributes balance: account.balance - 50
+```ruby
+# yuck!
+account.update_attributes balance: account.balance - 50
 
-    # much better
-    account.withdraw amount: 50
+# much better
+account.withdraw amount: 50
+```
 
 But there are multiple complications with the OO approach. How do we integrate
 Rails style validations? How are user-supplied strings type converted? How do we
@@ -28,27 +30,35 @@ know if the command succeeded? CommandModel solves these problems.
 
 Add this line to your application's Gemfile:
 
-    gem 'command_model'
+```ruby
+gem 'command_model'
+```
 
 And then execute:
 
-    $ bundle
+```console
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install command_model
+```console
+$ gem install command_model
+```
 
 ## Usage
 
 Create a class derived from CommandModel::Model to represent the command
 request.
 
-    class WithdrawCommand < CommandModel::Model
-      parameter :amount,
-        convert: :integer,
-        presence: true,
-        numericality: { greater_than: 0, less_than_or_equal_to: 500 }
-    end
+```ruby
+class WithdrawCommand < CommandModel::Model
+  parameter :amount,
+    convert: :integer,
+    presence: true,
+    numericality: { greater_than: 0, less_than_or_equal_to: 500 }
+end
+```
 
 Create the method to run the command. This method should instantiate and call a new command object. It must pass call
 a block that actually does the work. The block will only be called if
@@ -57,32 +67,36 @@ any further validations that only can be done during execution. If it adds
 any errors to the command object then the command will be considered to have
 failed. Finally, the call method will return self.
 
-    class Account
-      # ...
-
-      def withdraw(args)
-        WithdrawCommand.new(args).call do |command|
-          if balance >= command.amount
-            @balance -= command.amount
-          else
-            command.errors.add :amount, "is more than account balance"
-          end
-        end
-      end
+```ruby
+class Account
+  # ...
 
-      # ...
+  def withdraw(args)
+    WithdrawCommand.new(args).call do |command|
+      if balance >= command.amount
+        @balance -= command.amount
+      else
+        command.errors.add :amount, "is more than account balance"
+      end
     end
+  end
+
+  # ...
+end
+```
 
 Use example:
 
-    response = account.withdraw amount: 50
+```ruby
+response = account.withdraw amount: 50
 
-    if response.success?
-      puts "Success!"
-    else
-      puts "Errors:"
-      puts response.errors.full_messages
-    end
+if response.success?
+  puts "Success!"
+else
+  puts "Errors:"
+  puts response.errors.full_messages
+end
+```
 
 ## Mixing in Domain Logic
 
@@ -93,28 +107,73 @@ method. The execute method is called by the call method if all validations
 succeed. The following is a reimplementation of the previous example with
 internal domain logic.
 
-    class WithdrawCommand < CommandModel::Model
-      parameter :amount,
-        convert: :integer,
-        presence: true,
-        numericality: { greater_than: 0, less_than_or_equal_to: 500 }
-      parameter :account_id, presence: true
-
-      def execute
-        account = Account.find_by_id account_id
-        unless account
-          errors.add :account_id, "not found"
-          return
-        end
-
-        if account.balance >= amount
-          account.balance -= amount
-        else
-          errors.add :amount, "is more than account balance"
-        end
-      end
+```ruby
+class WithdrawCommand < CommandModel::Model
+  parameter :amount,
+    convert: :integer,
+    presence: true,
+    numericality: { greater_than: 0, less_than_or_equal_to: 500 }
+  parameter :account_id, presence: true
+
+  def execute
+    account = Account.find_by_id account_id
+    unless account
+      errors.add :account_id, "not found"
+      return
+    end
+
+    if account.balance >= amount
+      account.balance -= amount
+    else
+      errors.add :amount, "is more than account balance"
+    end
+  end
+end
+```
+
+## Dependencies
+
+Sometimes a command has requires values that are not supplied by the user. For example, a command may require the
+current user, a database connection, or a logger. These dependencies can be specified with the `dependency` method. The following example adds filtering to ensure that the current user owns the account.
+
+```ruby
+class WithdrawCommand < CommandModel::Model
+  dependency :current_user
+
+  parameter :amount,
+    convert: :integer,
+    presence: true,
+    numericality: { greater_than: 0, less_than_or_equal_to: 500 }
+  parameter :account_id, presence: true
+
+  def execute
+    account = current_user.accounts.find_by_id account_id
+    unless account
+      errors.add :account_id, "not found"
+      return
     end
 
+    if account.balance >= amount
+      account.balance -= amount
+    else
+      errors.add :amount, "is more than account balance"
+    end
+  end
+end
+```
+
+This command could be called as follows.
+
+```ruby
+WithdrawCommand.execute({amount: 200}, {current_user: current_user})
+```
+
+## Inheritance
+
+Subclasses of `CommandModel::Model` can themselves be subclassed. Parameter and dependency definitions will be copied at
+the time of subclassing. If the superclass is later modified, the parameter and dependency definitions of the subclasses
+will not be modified. This may be changed in the future.
+
 ## Other uses
 
 This could be used to wrap database generated errors into normal Rails
@@ -128,8 +187,30 @@ be doing a uniqueness check anyway.
 There is a simple Rails application in examples/bank that demonstrates the
 integration of Rails form helpers and validations with CommandModel.
 
+## Testing
+
+```console
+$ bundle install
+$ rake
+```
+
+To test against a specific version of Rails / ActiveModel set the BUNDLE_GEMFILE environment variable. For example, to
+test Rails 6.1:
+
+```console
+$ BUNDLE_GEMFILE=gemfiles/6.1.gemfile bundle install
+$ BUNDLE_GEMFILE=gemfiles/6.1.gemfile rake
+```
+
 ## Version History
 
+* 2.1.0 - March 15, 2023
+    * Add dependencies to CommandModel::Model
+    * Allow inheritance of CommandModel::Model
+    * Require Ruby 3.2+
+    * Require Rails / ActiveModel 6.1+
+* 2.0.1 - April 3, 2023
+    * Date parsing allows 5 digit years
 * 2.0 - April 11, 2018
     * Rename typecast parameter option to convert
     * Any callable object can be used as a type converter

data/Rakefile

@@ -1,10 +1,7 @@
-#!/usr/bin/env rake
+require "bundler/setup"
 require "bundler/gem_tasks"
 
-begin
-    require 'rspec/core/rake_task'
-      RSpec::Core::RakeTask.new(:spec)
-rescue LoadError
-end
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task default: :spec

data/bin/rake

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rake", "rake")

data/command_model.gemspec

@@ -9,16 +9,15 @@ Gem::Specification.new do |gem|
   gem.homepage      = "https://github.com/JackC/command_model"
 
   gem.files         = `git ls-files`.split($\)
-  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.name          = "command_model"
   gem.require_paths = ["lib"]
   gem.version       = CommandModel::VERSION
 
-  gem.required_ruby_version = '>= 2.5.0'
+  gem.required_ruby_version = '>= 3.2.0'
 
-  gem.add_dependency 'activemodel', "> 5.0"
+  gem.add_dependency 'activemodel', "> 6.1"
 
-  gem.add_development_dependency 'rake', "~> 12.3.0"
-  gem.add_development_dependency 'rspec', "~> 3.7.0"
+  gem.add_development_dependency 'rake', "~> 13.1.0"
+  gem.add_development_dependency 'rspec', "~> 3.13.0"
 end

data/examples/bank/Gemfile

@@ -3,9 +3,9 @@ source 'https://rubygems.org'
 gem 'rails', '3.2.8'
 
 # Bundle edge Rails instead:
-# gem 'rails', :git => 'git://github.com/rails/rails.git'
+# gem 'rails', git: 'git://github.com/rails/rails.git'
 
-gem 'command_model', :path => '../..'
+gem 'command_model', path: '../..'
 
 
 # Gems used only for assets and not required
@@ -15,7 +15,7 @@ group :assets do
   gem 'coffee-rails', '~> 3.2.1'
 
   # See https://github.com/sstephenson/execjs#readme for more supported runtimes
-  # gem 'therubyracer', :platform => :ruby
+  # gem 'therubyracer', platform: :ruby
 
   gem 'uglifier', '>= 1.0.3'
 end
@@ -35,4 +35,4 @@ gem 'jquery-rails'
 # gem 'capistrano'
 
 # To use debugger
-# gem 'ruby-debug19', :require => 'ruby-debug'
+# gem 'ruby-debug19', require: 'ruby-debug'

data/examples/bank/app/controllers/accounts_controller.rb

@@ -7,44 +7,44 @@
     @account = Account.find_by_name params[:id]
     @deposit = Account::DepositCommand.new
   end
-  
+
   def deposit
     @account = Account.find_by_name params[:id]
     @deposit = @account.deposit params[:deposit]
-    
+
     if @deposit.success?
-      redirect_to root_path, :notice => "Deposited #{@deposit.amount} to #{@account.name}'s account."
+      redirect_to root_path, notice: "Deposited #{@deposit.amount} to #{@account.name}'s account."
     else
       render "deposit_form"
     end
   end
-  
+
   def withdraw_form
     @account = Account.find_by_name params[:id]
     @withdraw = Account::WithdrawCommand.new
-  end  
-  
+  end
+
   def withdraw
     @account = Account.find_by_name params[:id]
     @withdraw = @account.withdraw params[:withdraw]
-    
+
     if @withdraw.success?
-      redirect_to root_path, :notice => "Withdrew #{@withdraw.amount} from #{@account.name}'s account."
+      redirect_to root_path, notice: "Withdrew #{@withdraw.amount} from #{@account.name}'s account."
     else
       render "withdraw_form"
-    end  
+    end
   end
 
   def transfer_form
     @accounts = Account.all
     @transfer = Account::TransferCommand.new
   end
-  
+
   def transfer
     @transfer = Account::TransferCommand.new(params[:transfer])
-    
+
     if @transfer.call.success?
-      redirect_to root_path, :notice => "Transferred #{@transfer.amount} from #{@transfer.from.name}'s account to #{@transfer.to.name}'s account."
+      redirect_to root_path, notice: "Transferred #{@transfer.amount} from #{@transfer.from.name}'s account to #{@transfer.to.name}'s account."
     else
       @accounts = Account.all
       render "transfer_form"

data/examples/bank/app/controllers/transfers_controller.rb

@@ -3,12 +3,12 @@ class TransfersController < ApplicationController
     @accounts = Account.all
     @transfer = Account::Transfer.new
   end
-  
+
   def create
     @transfer = Account::Transfer.new(params[:transfer])
-    
+
     if @transfer.call.success?
-      redirect_to root_path, :notice => "Transferred #{@transfer.amount} from #{@transfer.from.name}'s account to #{@transfer.to.name}'s account."
+      redirect_to root_path, notice: "Transferred #{@transfer.amount} from #{@transfer.from.name}'s account to #{@transfer.to.name}'s account."
     else
       @accounts = Account.all
       render :new

data/examples/bank/app/views/accounts/deposit_form.html.erb

@@ -12,12 +12,8 @@
   </ul>
 <% end %>
 
-<%= form_for @deposit, :as => :deposit, :url => account_deposit_path(@account) do |f| %>
+<%= form_for @deposit, as: :deposit, url: account_deposit_path(@account) do |f| %>
   <%= f.label :amount %>
   <%= f.text_field :amount %>
   <%= f.submit "Deposit" %>
 <% end %>
-
-
-
-

data/examples/bank/app/views/accounts/withdraw_form.html.erb

@@ -12,12 +12,8 @@
   </ul>
 <% end %>
 
-<%= form_for @withdraw, :as => :withdraw, :url => account_withdraw_path(@account) do |f| %>
+<%= form_for @withdraw, as: :withdraw, url: account_withdraw_path(@account) do |f| %>
   <%= f.label :amount %>
   <%= f.text_field :amount %>
   <%= f.submit "Deposit" %>
 <% end %>
-
-
-
-

data/examples/bank/app/views/layouts/application.html.erb

@@ -2,7 +2,7 @@
 <html>
 <head>
   <title>Bank</title>
-  <%= stylesheet_link_tag    "application", :media => "all" %>
+  <%= stylesheet_link_tag    "application", media: "all" %>
   <%= javascript_include_tag "application" %>
   <%= csrf_meta_tags %>
 </head>

data/examples/bank/app/views/transfers/new.html.erb

@@ -14,11 +14,11 @@
 <%= form_for @transfer do |f| %>
   <div>
     <%= f.label :from_name %><br />
-    <%= f.select :from_name, @accounts.map { |a| ["#{a.name} - #{a.balance}", a.name] }, :selected => f.object.from_name, :include_blank => true %>
+    <%= f.select :from_name, @accounts.map { |a| ["#{a.name} - #{a.balance}", a.name] }, selected: f.object.from_name, include_blank: true %>
   </div>
   <div>
     <%= f.label :to_name %><br />
-    <%= f.select :to_name, @accounts.map { |a| ["#{a.name} - #{a.balance}", a.name] }, :selected => f.object.to_name, :include_blank => true %>
+    <%= f.select :to_name, @accounts.map { |a| ["#{a.name} - #{a.balance}", a.name] }, selected: f.object.to_name, include_blank: true %>
   </div>
   <div>
     <%= f.label :amount %><br />
@@ -26,7 +26,3 @@
   </div>
   <%= f.submit "Transfer" %>
 <% end %>
-
-
-
-

data/examples/bank/config/application.rb

@@ -10,7 +10,7 @@ require "rails/test_unit/railtie"
 
 if defined?(Bundler)
   # If you precompile assets before deploying to production, use this line
-  Bundler.require(*Rails.groups(:assets => %w(development test)))
+  Bundler.require(*Rails.groups(assets: %w(development test)))
   # If you want your assets lazily compiled in production, use this line
   # Bundler.require(:default, :assets, Rails.env)
 end

data/examples/bank/config/routes.rb

@@ -1,11 +1,11 @@
 Bank::Application.routes.draw do
-  get "accounts/:id/withdraw" => "accounts#withdraw_form", :as => :account_withdraw_form
-  post "accounts/:id/withdraw" => "accounts#withdraw", :as => :account_withdraw
-  
-  get "accounts/:id/deposit" => "accounts#deposit_form", :as => :account_deposit_form
-  post "accounts/:id/deposit" => "accounts#deposit", :as => :account_deposit
+  get "accounts/:id/withdraw" => "accounts#withdraw_form", as: :account_withdraw_form
+  post "accounts/:id/withdraw" => "accounts#withdraw", as: :account_withdraw
+
+  get "accounts/:id/deposit" => "accounts#deposit_form", as: :account_deposit_form
+  post "accounts/:id/deposit" => "accounts#deposit", as: :account_deposit
 
   resources :transfers, only: %w[new create]
 
-  root :to => "accounts#index"
+  root to: "accounts#index"
 end

data/examples/bank/test/performance/browsing_test.rb

@@ -3,8 +3,8 @@ require 'rails/performance_test_help'
 
 class BrowsingTest < ActionDispatch::PerformanceTest
   # Refer to the documentation for all available options
-  # self.profile_options = { :runs => 5, :metrics => [:wall_time, :memory]
-  #                          :output => 'tmp/performance', :formats => [:flat] }
+  # self.profile_options = { runs: 5, metrics: [:wall_time, :memory]
+  #                          output: 'tmp/performance', formats: [:flat] }
 
   def test_homepage
     get '/'

data/gemfiles/{5.0.gemfile → 6.1.gemfile}

@@ -1,5 +1,5 @@
 source "https://rubygems.org"
 
-gem "activemodel", "~> 5.0.0"
+gem "activemodel", "~> 6.1.0"
 
 gemspec :path=>"../"