statusable 0.1.0.pre → 0.2.0.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25c9dd86e72394b2b8e82391af2c925c3b2ab2bab6db1fc2c6620c2d8d51f502
-  data.tar.gz: f04aa28c9f999d8594f632d5892bb1ed8aa11c7db6dfb89f064930dcca17ba93
+  metadata.gz: 6abf9f62c9ce28ec0003fe73731760adc77dd2e6fad64f05165279d2cb575684
+  data.tar.gz: db4e4a6a8dd888ee50dc489defe0e44c6b225a68a07ec1c41e02b4194eb6d4f8
 SHA512:
-  metadata.gz: 5a45c11415d8f4122f3a11da376c2ec68b8f502d255386efe96b957fbb1535e52bdc4a16a199c548c0ee8145969894b3be1712094d564742f6897b653e65e004
-  data.tar.gz: 516c253ee89fd0251e3b4cf9ccb4af45c2447ffbebf97abc4b5beddf58d0fe6066301360172c18f822e889445556dea0def970a70eb24d39df5e8aee082aa24c
+  metadata.gz: db814ddca7cffb1c14facd97dadc88d341616a4357e32822f254a9b0d6196103bc17022549955f58cd4db71544295a409381fcc08e022a5a366586d8110cd793
+  data.tar.gz: aa2482d72ee291e07f8b40f3e5e4c9d26b518508c0214974695b51687d8735f3d92a7d991372219dd88c1b87bc9be4432eb4bc8c17c0a504ad16734d58f7ffbd

data/README.md

@@ -1,11 +1,58 @@
 # Statusable
 
+[![Gem Version](https://img.shields.io/github/v/release/pdobb/statusable)](https://img.shields.io/github/v/release/pdobb/statusable)
+
 Statusable adds a `has_statuses` macro for defining common status-related methods for use with ActiveRecord objects / Relations.
 
-## Usage
+## Installation
+
+Add this line to your application's Gemfile:
 
 ```ruby
-class MyModel < ApplicationRecord
+gem "statusable"
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Or install it yourself:
+
+```bash
+$ gem install statusable
+```
+
+## Configuration
+
+First, add a `status` column to your model. Or pick any other name you may want instead of `status`... the column name is configurable. (See [Advanced Usage](#advanced-usage).)
+
+```ruby
+# db/migrate/<version>_add_status_to_jobs.rb
+
+def change
+  add_column :jobs, :status, :string, null: false, default: "Initializing"
+  add_index :jobs, :status
+end
+```
+
+Next, include `Statusable::HasStatuses` either into your model or into ApplicationRecord, per your preference.
+
+```ruby
+class Job < ApplicationRecord
+  include Statusable::HasStatuses
+end
+```
+
+Finally, call the `has_statuses` macro in your model, along with an array of your desired status names. See below for [Basic Usage](#basic-usage) and [Advanced Usage](#advanced-usage).
+
+## Basic Usage
+
+```ruby
+class Job < ApplicationRecord
+  include Statusable::HasStatuses
+
   has_statuses(%w[
       Pending
       Running
@@ -14,22 +61,178 @@ class MyModel < ApplicationRecord
 end
 ```
 
-## Installation
-
-Add this line to your application's Gemfile:
+This adds a number of methods, named_scopes, and even ActiveModel validations to the model.
 
 ```ruby
-gem "statusable"
+# The following are equivalent:
+
+job = Job.new(status: "Pending")
+job = Job.new(status: Job.status_pending)
+job = Job.new; job.set_status_pending
+
+# Check current status:
+
+job.status_pending?    # => true
+job.status?("Pending") # => true
+
+job.not_status_running?    # => true
+job.not_status?("Running") # => true
+
+# Set status without saving:
+
+job.set_status_running
+# => #<Job:0x000000012fc3b060 id: nil, status: "Running", created_at: nil, updated_at: nil>
+job.status_running? # => true
+
+# Set status and save:
+
+job.set_status_running!
+# => #<Job:0x000000012fc3b560 id: 1, status: "Running", created_at: "...", updated_at: "...">
+
+# Get status names/lists:
+
+Job.status_pending # => "Pending"
+job.status_pending # => "Pending"
+
+Job.status_options # => ["Pending", "Running", "Completed"]
+job.status_options # => ["Pending", "Running", "Completed"]
+
+Job.humanized_statuses_list # => "Pending, Running, or Completed"
+job.humanized_statuses_list # => "Pending, Running, or Completed"
+
+# Named scopes:
+
+Job.for_status("Pending").to_sql
+# => SELECT "jobs".* FROM "jobs" WHERE "jobs"."status" = 'Pending'
+Job.for_status(%w[Pending Running]).to_sql
+# => SELECT "jobs".* FROM "jobs" WHERE "jobs"."status" IN ('Pending', 'Running')
+
+Job.not_for_status("Pending").to_sql
+# => SELECT "jobs".* FROM "jobs" WHERE "jobs"."status" != 'Pending'
+Job.not_for_status(%w[Pending Running]).to_sql
+# => SELECT "jobs".* FROM "jobs" WHERE "jobs"."status" NOT IN ('Pending', 'Running')
+
+Job.for_status_pending.to_sql
+# => SELECT "jobs".* FROM "jobs" WHERE "jobs"."status" = 'Pending'
+Job.not_for_status_pending.to_sql
+# => SELECT "jobs".* FROM "jobs" WHERE "jobs"."status" != 'Pending'
+
+Job.by_status_asc.to_sql
+# => SELECT "jobs".* FROM "jobs" ORDER BY "jobs"."status"
+Job.by_status_desc.to_sql
+# => SELECT "jobs".* FROM "jobs" ORDER BY "jobs"."status" DESC
+
+Job.group_by_status.to_sql
+# => SELECT "jobs".* FROM "jobs" GROUP BY "jobs"."status"
+
+# Validation:
+
+# By default, we don't validate on presence, but this can be changed.
+# See the Advanced Usage section.
+job.status = nil
+job.validate; job.errors[:status] # => []
+
+job.status = "Invalid Status"
+job.validate; job.errors[:status]
+# => ["must be one of Pending, Running, or Completed"]
 ```
 
-And then execute:
-```bash
-$ bundle
+## Advanced Usage
+
+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`
+
+_Note: Be sure that the column name in your migration matches whatever you choose for `col_name`, below._
+
+```ruby
+class Job < ApplicationRecord
+  include Statusable::HasStatuses
+
+  has_statuses(%w[
+      Pending
+      Running
+      Completed
+    ],
+    col_name: "lifecycle_state",
+    validate_presence: true,
+    validate_inclusion: true)
+end
 ```
 
-Or install it yourself as:
-```bash
-$ gem install statusable
+This adds a number of methods, named_scopes, and even ActiveModel validations to the model--the same ones shown in Basic Usage. However, the "status" name varies, and this time we include a presence validation:
+
+```ruby
+# The following are equivalent:
+
+job = Job.new; job.set_lifecycle_state_pending
+
+# Check current status:
+
+job.lifecycle_state_pending?    # => true
+job.lifecycle_state?("Pending") # => true
+
+job.not_lifecycle_state_running?    # => true
+job.not_lifecycle_state?("Running") # => true
+
+# Set status without saving:
+
+job.set_lifecycle_state_running
+# => #<Job:0x000000012fc3b060 id: nil, lifecycle_state: "Running", created_at: nil, updated_at: nil>
+job.lifecycle_state_running? # => true
+
+# Set status and save:
+
+job.set_lifecycle_state_running!
+# => #<Job:0x000000012fc3b560 id: 1, lifecycle_state: "Running", created_at: "...", updated_at: "...">
+
+# Get status names/lists:
+
+Job.lifecycle_state_pending # => "Pending"
+job.lifecycle_state_pending # => "Pending"
+
+Job.lifecycle_state_options # => ["Pending", "Running", "Completed"]
+job.lifecycle_state_options # => ["Pending", "Running", "Completed"]
+
+Job.humanized_lifecycle_states_list # => "Pending, Running, or Completed"
+job.humanized_lifecycle_states_list # => "Pending, Running, or Completed"
+
+# Named scopes:
+
+Job.for_lifecycle_state("Pending").to_sql
+# => SELECT "jobs".* FROM "jobs" WHERE "jobs"."lifecycle_state" = 'Pending'
+Job.for_lifecycle_state(%w[Pending Running]).to_sql
+# => SELECT "jobs".* FROM "jobs" WHERE "jobs"."lifecycle_state" IN ('Pending', 'Running')
+
+Job.not_for_lifecycle_state("Pending").to_sql
+# => SELECT "jobs".* FROM "jobs" WHERE "jobs"."lifecycle_state" != 'Pending'
+Job.not_for_lifecycle_state(%w[Pending Running]).to_sql
+# => SELECT "jobs".* FROM "jobs" WHERE "jobs"."lifecycle_state" NOT IN ('Pending', 'Running')
+
+Job.for_lifecycle_state_pending.to_sql
+# => SELECT "jobs".* FROM "jobs" WHERE "jobs"."lifecycle_state" = 'Pending'
+Job.not_for_lifecycle_state_pending.to_sql
+# => SELECT "jobs".* FROM "jobs" WHERE "jobs"."lifecycle_state" != 'Pending'
+
+Job.by_lifecycle_state_asc.to_sql
+# => SELECT "jobs".* FROM "jobs" ORDER BY "jobs"."lifecycle_state"
+Job.by_lifecycle_state_desc.to_sql
+# => SELECT "jobs".* FROM "jobs" ORDER BY "jobs"."lifecycle_state" DESC
+
+Job.group_by_lifecycle_state.to_sql
+# => SELECT "jobs".* FROM "jobs" GROUP BY "jobs"."lifecycle_state"
+
+# Validation:
+
+job.lifecycle_state = nil
+job.validate; job.errors[:lifecycle_state] # => ["can't be blank"]
+
+job.lifecycle_state = "Invalid lifecycle_state"
+job.validate; job.errors[:lifecycle_state]
+# => ["must be one of Pending, Running, or Completed"]
 ```
 
 ## Contributing

data/lib/statusable/has_statuses.rb

@@ -12,18 +12,15 @@ module Statusable::HasStatuses
   class_methods do # rubocop:disable Metrics/BlockLength
     # rubocop:disable Metrics/AbcSize
     # rubocop:disable Metrics/MethodLength
-    # rubocop:disable Metrics/PerceivedComplexity
     # rubocop:disable Naming/PredicateName
     def has_statuses(
           *args,
           col_name: "status",
-          arel_column: nil,
-          validate_inclusion: true,
-          validate_presence: false)
+          validate_presence: false,
+          validate_inclusion: true)
       statuses = args.flatten.freeze
-
-      arel_column ||= arel_table[col_name]
       pluralized_column_name = col_name.to_s.pluralize
+      arel_column = arel_table[col_name]
 
       humanized_statuses_list =
         statuses.to_sentence(
@@ -31,18 +28,20 @@ module Statusable::HasStatuses
           last_word_connector: ", or ").
           freeze
 
-      if validate_inclusion
-        validates col_name,
-                  inclusion: {
-                    in: statuses,
-                    allow_blank: true,
-                    message: "must be one of #{humanized_statuses_list}",
-                  }
+      if validate_presence
+        validates(
+          col_name,
+          presence: true)
       end
 
-      if validate_presence
-        validates col_name,
-                  presence: true
+      if validate_inclusion
+        validates(
+          col_name,
+          inclusion: {
+            in: statuses,
+            allow_blank: true,
+            message: "must be one of #{humanized_statuses_list}",
+          })
       end
 
       # .for_status(<status>)
@@ -103,6 +102,16 @@ module Statusable::HasStatuses
         statuses
       end
 
+      # #status?("Ready")
+      define_method(:"#{col_name}?") do |a_status|
+        public_send(col_name) == a_status
+      end
+
+      # #not_status?("Ready")
+      define_method(:"not_#{col_name}?") do |a_status|
+        public_send(col_name) != a_status
+      end
+
       statuses.each do |status| # rubocop:disable Metrics/BlockLength
         status_name = status.parameterize.underscore
 
@@ -154,15 +163,9 @@ module Statusable::HasStatuses
         define_method(:"not_#{col_name}_#{status_name}?") do
           public_send(col_name) != status
         end
-
-        # #status?(<a_status>)
-        define_method(:"#{col_name}?") do |a_status|
-          public_send(col_name) == a_status
-        end
       end
     end
     # rubocop:enable Naming/PredicateName
-    # rubocop:enable Metrics/PerceivedComplexity
     # rubocop:enable Metrics/MethodLength
     # rubocop:enable Metrics/AbcSize
   end

data/lib/statusable/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: statusable
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre
+  version: 0.2.0.pre
 platform: ruby
 authors:
 - Paul DobbinSchmaltz
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-08-15 00:00:00.000000000 Z
+date: 2024-08-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails