statusable 0.2.0.pre → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6abf9f62c9ce28ec0003fe73731760adc77dd2e6fad64f05165279d2cb575684
-  data.tar.gz: db4e4a6a8dd888ee50dc489defe0e44c6b225a68a07ec1c41e02b4194eb6d4f8
+  metadata.gz: b529e80d12f7c2f085b89f9ed98fc9abd70e47f2a823c814005bad5243c0bed6
+  data.tar.gz: 503ce3bedca223203c854a936ff4b98ca04a2efe60a8a61d58b530dbe66c56d9
 SHA512:
-  metadata.gz: db814ddca7cffb1c14facd97dadc88d341616a4357e32822f254a9b0d6196103bc17022549955f58cd4db71544295a409381fcc08e022a5a366586d8110cd793
-  data.tar.gz: aa2482d72ee291e07f8b40f3e5e4c9d26b518508c0214974695b51687d8735f3d92a7d991372219dd88c1b87bc9be4432eb4bc8c17c0a504ad16734d58f7ffbd
+  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,7 +246,34 @@ 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`.
 
-To release a new version, update the version number in `version.rb` and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+### Testing
+
+To test this gem:
+
+```bash
+rake
+```
+
+#### Linters
+
+```bash
+rubocop
+
+reek
+
+npx prettier . --check
+npx prettier . --write
+```
+
+### Releases
+
+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`
+3. Run `bundle` to update Gemfile.lock with the latest version info
+4. Commit the changes. e.g. `Bump to vX.Y.Z`
+5. Run `rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## License
 

data/lib/statusable/has_statuses.rb

@@ -28,125 +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")
+      # 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|
-        public_send(col_name) == 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!
@@ -154,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.2.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.2.0.pre
+  version: 0.4.0
 platform: ruby
 authors:
 - Paul DobbinSchmaltz
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-08-16 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