statusable 0.3.0.pre → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08042127a22da0aacac6b596858eadf3dbbcbf4e0afdd3ff8713807a579f0960'
-  data.tar.gz: cca9c44afb9772931d2a8b3e6b1c06ce9b765674762d0c47423e61b87ac1a634
+  metadata.gz: b529e80d12f7c2f085b89f9ed98fc9abd70e47f2a823c814005bad5243c0bed6
+  data.tar.gz: 503ce3bedca223203c854a936ff4b98ca04a2efe60a8a61d58b530dbe66c56d9
 SHA512:
-  metadata.gz: df801462f17e8287a0885a001d97c71906a579c296851e113698f0c6ae3c2df02d7d249cb7dd8ef74906ea07c2e451d51c186580cce9af954e5846358d79629e
-  data.tar.gz: 0e7b0fcaaf55e968d4d97bdcaadf4f3d8ca820498d737146f4b08fb739657cde63033567a336d1342dab38b50f56d731ed653b5b7d5134e442a897472aa6d742
+  metadata.gz: aebb2e90c390cc59bde1e77de2c4468d35bc5acfe339092ac598b5f4f547dca04d04d6b8d5dd7f78ad7828baabc24d8e3842349c8e94a7fc11e4b417beb54cf3
+  data.tar.gz: 4d7f1525ffc1ff3a80be61fac81095649aaf9eecd2b43c48f11edd96034be506c2c39cf801117f3a82b1ea2f348b68f4d845e28f40fbedbcb10b8ef47d4ff957

data/README.md

@@ -142,6 +142,7 @@ job.validate; job.errors[:status]
 The column name is customizable, as is whether or not to validate on presence or inclusion. Validating on inclusion means: ensuring that the current status value is included in the list of possible status values.
 
 Defaults:
+
 - `col_name = "status"`
 - `validate_presence = false`
 - `validate_inclusion = true`
@@ -245,9 +246,28 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bundle exec rake install`.
 
+### Testing
+
+To test this gem:
+
+```bash
+rake
+```
+
+#### Linters
+
+```bash
+rubocop
+
+reek
+
+npx prettier . --check
+npx prettier . --write
+```
+
 ### Releases
 
-To release a new version of Statusable to RubyGems:
+To release a new version of this gem to RubyGems:
 
 1. Update the version number in `version.rb`
 2. Update the release date, etc. in `CHANGELOG.md`

data/lib/statusable/has_statuses.rb

@@ -28,126 +28,289 @@ module Statusable::HasStatuses
           last_word_connector: ", or ").
           freeze
 
-      if validate_presence
-        validates(
-          col_name,
-          presence: true)
+      # VALIDATIONS
+
+      # Define a presence validation on the given `col_name`, if requested.
+      if validate_presence # rubocop:disable Style/IfUnlessModifier
+        validates(col_name, presence: true)
       end
 
+      # Define an inclusion validation on the given `col_name` based on the
+      # givien list of `statuses`, if requested.
       if validate_inclusion
+        message = "must be one of #{humanized_statuses_list}"
         validates(
           col_name,
-          inclusion: {
-            in: statuses,
-            allow_blank: true,
-            message: "must be one of #{humanized_statuses_list}",
-          })
+          inclusion: { in: statuses, allow_blank: true, message: message })
       end
 
-      # .for_status(<status>)
-      scope "for_#{col_name}",
-            ->(status) {
-              where(
-                if status.is_a?(Array)
-                  arel_column.in(status)
-                else
-                  arel_column.eq(status)
-                end)
-            }
-
-      # .not_for_status(<status>)
-      scope "not_for_#{col_name}",
-            ->(status) {
-              where(
-                if status.is_a?(Array)
-                  arel_column.not_in(status)
-                else
-                  arel_column.not_eq(status)
-                end)
-            }
-
-      # .by_status_asc
-      scope "by_#{col_name}_asc",
-            -> { order(arel_column) }
-
-      # .by_status_desc
-      scope "by_#{col_name}_desc",
-            -> { order(arel_column.desc) }
-
-      # .group_by_status
-      scope "group_by_#{col_name}",
-            -> { group(arel_column) }
-
-      # Class method to get a humanized list of statuses.
-      # .humanized_statuses_list
-      define_singleton_method(:"humanized_#{pluralized_column_name}_list") do
-        humanized_statuses_list
-      end
+      # NAMED SCOPES
 
-      # Instance method to get a humanized list of statuses.
-      # #humanized_statuses_list
-      define_method(:"humanized_#{pluralized_column_name}_list") do
-        humanized_statuses_list
-      end
+      # Define a named scope that filters on `col_name` records.
+      #
+      # @attr status [String, Array[String]]
+      #
+      # @example Default `col_name`
+      #   .for_status(<a_status_name>)
+      #
+      # @example Custom `col_name`
+      #   .for_custom_col_name(<a_status_name>)
+      scope :"for_#{col_name}", ->(status) {
+        method_name = status.is_a?(Array) ? :in : :eq
+        where(arel_column.public_send(method_name, status))
+      }
+
+      # Define a named scope that filters out `col_name` records.
+      #
+      # @attr status [String, Array[String]]
+      #
+      # @example Default `col_name`
+      #   .not_for_status(<a_status_name>)
+      #
+      # @example Custom `col_name`
+      #   .not_for_custom_col_name(<a_status_name>)
+      scope :"not_for_#{col_name}", ->(status) {
+        method_name = status.is_a?(Array) ? :not_in : :not_eq
+        where(arel_column.public_send(method_name, status))
+      }
+
+      # Define a named scope that orders by `col_name`, ascending.
+      #
+      # @example Default `col_name`
+      #   .by_status_asc
+      #
+      # @example Custom `col_name`
+      #   .by_custom_col_name_asc
+      scope :"by_#{col_name}_asc", -> { order(arel_column) }
+
+      # Define a named scope that orders by `col_name`, descending.
+      #
+      # @example Default `col_name`
+      #   .by_status_desc
+      #
+      # @example Custom `col_name`
+      #   .by_custom_col_name_desc
+      scope :"by_#{col_name}_desc", -> { order(arel_column.desc) }
+
+      # Define a named scope that groups by `col_name`, ascending.
+      #
+      # @example Default `col_name`
+      #   .group_by_status
+      #
+      # @example Custom `col_name`
+      #   .group_by_custom_col_name
+      scope :"group_by_#{col_name}", -> { group(arel_column) }
+
+      # CLASS METHODS
 
-      # Class method to get all options for <col_name>.
-      # .status_options
+      # Define a class method that returns the `statuses` Array.
+      #
+      # @return [Array[String]]
+      #
+      # @example Default `col_name`
+      #   .status_options          # => ["Status 1", "Status 2"]
+      #
+      # @example Custom `col_name`
+      #   .custom_col_name_options # => ["Custom 1", "Custom 2"]
       define_singleton_method(:"#{col_name}_options") do
         statuses
       end
 
-      # Instance method to get all options for <col_name>.
-      # #status_options
+      # Define a class method that returns a humanized list of `statuses`.
+      #
+      # @return [String]
+      #
+      # @example Default `col_name`
+      #   .humanized_statuses_list # => "Status 1, Status 2, or Status 3"
+      #
+      # @example Custom `col_name`
+      #   .humanized_custom_col_name_list # => "Custom 1, Custom 2, or Custom 3"
+      define_singleton_method(:"humanized_#{pluralized_column_name}_list") do
+        humanized_statuses_list
+      end
+
+      # INSTANCE METHODS
+
+      # Define an instance method that returns the `statuses` Array.
+      #
+      # @return [Array[String]]
+      #
+      # @example Default `col_name`
+      #   #status_options          # => ["Status 1", "Status 2"]
+      #
+      # @example Custom `col_name`
+      #   #custom_col_name_options # => ["Custom 1", "Custom 2"]
       define_method(:"#{col_name}_options") do
         statuses
       end
 
-      # #status?("Ready")
-      # #status?(["Ready", "Not Ready"])
+      # Define an instance method that returns a humanized list of `statuses`.
+      #
+      # @return [String]
+      #
+      # @example Default `col_name`
+      #   #humanized_statuses_list # => "Status 1, Status 2, or Status 3"
+      #
+      # @example Custom `col_name`
+      #   #humanized_custom_col_name_list # => "Custom 1, Custom 2, or Custom 3"
+      define_method(:"humanized_#{pluralized_column_name}_list") do
+        humanized_statuses_list
+      end
+
+      # Define an instance method that checks whether:
+      # - The current `status` is the same as the given status
+      # - The current `status` is the same as any of the given statuses
+      #
+      # @return [Boolean]
+      #
+      # @example Default `col_name`
+      #   #status?("Known Status") # => true
+      #   #status?("Unknown Status") # => false
+      #   #status?(["Known Status 1", "Unknown Status 1"]) # => true
+      #   #status?(["Unknown Status 1", "Unknown Status 2"]) # => false
+      #
+      # @example Custom `col_name`
+      #   #custom_col_name?("Known Custom") # => true
+      #   #custom_col_name?("Unknown Custom") # => false
+      #   #custom_col_name?(["Known Custom 1", "Unknown Custom 1"]) # => true
+      #   #custom_col_name?(["Unknown Custom 1", "Unknown Custom 2"]) # => false
       define_method(:"#{col_name}?") do |a_status|
         Array(a_status).any?(public_send(col_name))
       end
 
-      # #not_status?("Ready")
+      # rubocop:disable Layout/LineLength
+
+      # Define an instance method that checks whether:
+      # - The current `status` is not the same as given status
+      # - The current `status` is not the same as any of the given statuses
+      #
+      # @return [Boolean]
+      #
+      # @example Default `col_name`
+      #   #not_status?("Known Status") # => false
+      #   #not_status?("Unknown Status") # => true
+      #   #not_status?(["Known Status 1", "Unknown Status 1"]) # => false
+      #   #not_status?(["Unknown Status 1", "Unknown Status 2"]) # => true
+      #
+      # @example Custom `col_name`
+      #   #not_custom_col_name?("Known Custom") # => false
+      #   #not_custom_col_name?("Unknown Custom") # => true
+      #   #not_custom_col_name?(["Known Custom 1", "Unknown Custom 1"]) # => false
+      #   #not_custom_col_name?(["Unknown Custom 1", "Unknown Custom 2"]) # => true
       define_method(:"not_#{col_name}?") do |a_status|
-        public_send(col_name) != a_status
+        Array(a_status).none?(public_send(col_name))
       end
 
+      # rubocop:enable Layout/LineLength
+
+      # INDIVIDUAL STATUS-SPECIFIC SCOPES/METHODS
+
       statuses.each do |status| # rubocop:disable Metrics/BlockLength
         status_name = status.parameterize.underscore
 
-        # .for_status_ready
-        scope "for_#{col_name}_#{status_name}",
+        # NAMED SCOPES
+
+        # Define a named scope that filters on `col_name` records that match
+        # this `status`.
+        #
+        # @example Default `col_name`
+        #   .for_status_ready
+        #   .for_status_not_ready
+        #
+        # @example Custom `col_name`
+        #   .for_custom_col_name_custom_1
+        #   .for_custom_col_name_custom_2
+        scope :"for_#{col_name}_#{status_name}",
               -> { where(arel_column.eq(status)) }
 
-        # .not_for_status_ready
-        scope "not_for_#{col_name}_#{status_name}",
+        # Define a named scope that filters on `col_name` records that do not
+        # match this `status`.
+        #
+        # @example Default `col_name`
+        #   .not_for_status_ready
+        #   .not_for_status_not_ready
+        #
+        # @example Custom `col_name`
+        #   .not_for_custom_col_name_custom_1
+        #   .not_for_custom_col_name_custom_2
+        scope :"not_for_#{col_name}_#{status_name}",
               -> { where(arel_column.not_eq(status)) }
 
-        # Class method to get <status_name> value. Obviates the need for
-        # defining a constant.
-        # .status_ready  # => "Ready"
+        # CLASS METHODS
+
+        # Define a class method that returns this `status`'s value. This
+        # obviates the need to define a constant on the including Class.
+        #
+        # @return [String]
+        #
+        # @example Default `col_name`
+        #   .status_ready     # => "Ready"
+        #   .status_not_ready # => "Not Ready"
+        #
+        # @example Custom `col_name`
+        #   .custom_col_name_custom_1 # => "Custom 1"
+        #   .custom_col_name_custom_2 # => "Custom 2"
         define_singleton_method(:"#{col_name}_#{status_name}") do
           status
         end
 
-        # Instance method to get <status_name> value. Obviates the need for
-        # defining a constant.
-        # #status_ready  # => "Ready"
+        # Define an instance method that returns this `status`'s value. This
+        # obviates the need to call e.g.
+        #  - `self.class::STATUS_READY`
+        #  - `self.class.status_ready`
+        # on the including Object.
+        #
+        # @return [String]
+        #
+        # @example Default `col_name`
+        #   #status_ready     # => "Ready"
+        #   #status_not_ready # => "Not Ready"
+        #
+        # @example Custom `col_name`
+        #   #custom_col_name_custom_1 # => "Custom 1"
+        #   #custom_col_name_custom_2 # => "Custom 2"
         define_method(:"#{col_name}_#{status_name}") do
           status
         end
 
+        # Define an instance method that sets this `status`'s value. This
+        # obviates the need to call e.g. `self.status = status_not_ready` on the
+        # including Object.
+        #
         # @return [self]
-        # #set_status_ready
+        #
+        # @example Default `col_name`
+        #   #set_status_ready.status     # => "Ready"
+        #   #set_status_not_ready.status # => "Not Ready"
+        #
+        # @example Custom `col_name`
+        #   #set_custom_col_name_custom_1.custom_col_name # => "Custom 1"
+        #   #set_custom_col_name_custom_2.custom_col_name # => "Custom 2"
         define_method(:"set_#{col_name}_#{status_name}") do
           public_send(:"#{col_name}=", status)
 
           self
         end
 
-        # #set_status_ready!
+        # Define an instance method that sets this `status`'s value, and then
+        # calls ActiveRecord::Persistence#save!. This obviates the need to call
+        # e.g. `self.status = status_not_ready; save!` on the including Object.
+        #
         # @return [self]
+        #
+        # @example Default `col_name`
+        #   #set_status_ready!.status # => "Ready"
+        #   #changes                  # => {}
+        #
+        #   #set_status_not_ready!.status # => "Not Ready"
+        #   #changes                      # => {}
+        #
+        # @example Custom `col_name`
+        #   #set_custom_col_name_custom_1!.custom_col_name # => "Custom 1"
+        #   #changes                  # => {}
+        #
+        #   #set_custom_col_name_custom_2!.custom_col_name # => "Custom 2"
+        #   #changes                  # => {}
         define_method(:"set_#{col_name}_#{status_name}!") do
           public_send(:"set_#{col_name}_#{status_name}")
           save!
@@ -155,12 +318,37 @@ module Statusable::HasStatuses
           self
         end
 
-        # #status_ready?
+        # Define an instance method that checks whether the current `status` is
+        # the same as the status named by this method name. This obviates the
+        # need to call e.g. `status == status_ready` on the including Object.
+        #
+        # @return [Boolean]
+        #
+        # @example Default `col_name`
+        #   #status_ready?     # => true
+        #   #status_not_ready? # => false
+        #
+        # @example Custom `col_name`
+        #   #custom_col_name_custom_1? # => true
+        #   #custom_col_name_custom_2? # => false
         define_method(:"#{col_name}_#{status_name}?") do
           public_send(col_name) == status
         end
 
-        # #not_status_ready?
+        # Define an instance method that checks whether the current `status` is
+        # not the same as the status named by this method name. This obviates
+        # the need to call e.g. `status != status_ready` on the including
+        # Object.
+        #
+        # @return [Boolean]
+        #
+        # @example Default `col_name`
+        #   #not_status_ready?     # => false
+        #   #not_status_not_ready? # => true
+        #
+        # @example Custom `col_name`
+        #   #not_custom_col_name_custom_1? # => false
+        #   #not_custom_col_name_custom_2? # => true
         define_method(:"not_#{col_name}_#{status_name}?") do
           public_send(col_name) != status
         end

data/lib/statusable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Statusable
-  VERSION = "0.3.0.pre"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: statusable
 version: !ruby/object:Gem::Version
-  version: 0.3.0.pre
+  version: 0.4.0
 platform: ruby
 authors:
 - Paul DobbinSchmaltz
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-08-26 00:00:00.000000000 Z
+date: 2024-11-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -98,14 +98,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.17
+rubygems_version: 3.3.27
 signing_key:
 specification_version: 4
 summary: Adds a `has_statuses` macro for defining common status-related ActiveRecord