lite-command 2.1.0 → 2.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: efd37a3a2fcbb8d90fef73088313f18bd281922d46594a4a57ee8dd34fcaf801
-  data.tar.gz: 4e88ca10b986095be52c3e454e70a6c8d7b3556bb4770ed51aca80d0b9beb894
+  metadata.gz: a80b87ce018b8d2c4097c6a3c1e22869b51089e7bb1e040f8b4be33f72a0cc47
+  data.tar.gz: 8db4399804fbdcd1ef0a42baa4ae902d864b8283cdb26ea0b8fdbac123f569c8
 SHA512:
-  metadata.gz: 4123ef0a3315a8b00796a58ca65b10bc2a51905dc59e663b1ffef2ec7f9becc700ae64216cb896024564993749979cd824087a68bac1e95532311dba29cd7aa0
-  data.tar.gz: dd4e22ead3d68f981319a372a0ce305f734f1745a31223daf725d93ff71cccbe1b4708e7b3d7ef4921f98f2e8df6c04939855b8a7e8d0e3292f5e7f3e0ec6c1a
+  metadata.gz: a00f4af0af22973c3ec4fa43e635d7bca891b97a3cebb264b52955dd1a9e9b963045297569cae7a6144820cb3cea0907044b73200f1f9a0781befded2fd1e0c1
+  data.tar.gz: 7a0239e49c62c900b1df6c39e0d7a6c97ac7768bb0e6b8b1292b44726a59e5f336a9d562c20fd4979f9950c1e7c3a57528ae2d83e5e85aee34379a75fdfbe1ce

data/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby:
+          - '3.3'
+          - '3.2'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{matrix.ruby}}
+          bundler-cache: true
+      - name: RSpec
+        run: bundle exec rspec .
+      - name: Fasterer
+        run: bundle exec fasterer .
+      - name: Rubocop
+        run: bundle exec rubocop .

data/CHANGELOG.md

@@ -6,13 +6,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.1.2] - 2024-10-08
+### Added
+- Allow `filled` to pass `{ empty: false }` to check if value is empty
+
+## [2.1.1] - 2024-10-06
+### Added
+- Added on_status hook to `execute!`
+### Changed
+- Reuse same attribute instance
+
 ## [2.1.0] - 2024-10-05
 ### Added
 - Added passing metadata to faults
 - Added `on_success` callback
 - Added `on_pending`, `on_executing`, `on_complete`, and `on_interrupted` callbacks
 - Added attributes and attribute validations
-- Added sequences
+- Added steps and sequences
+- Added fault streamer
 ### Changed
 - Check error descendency instead of type
 - Rename internal modules

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    lite-command (2.1.0)
+    lite-command (2.1.2)
       ostruct
 
 GEM

data/README.md

@@ -8,9 +8,9 @@ Lite::Command provides an API for building simple and complex command based serv
 
 Add this line to your application's Gemfile:
 
-> [!NOTE]
-> Gem versions `2.0.0`, `2.0.1`, `2.0.2`, and `2.0.3` are borked.
-> Version `2.1.0` is the latest working version.
+> [!WARNING]
+> Gem versions `~> 2.0` are borked.
+> Version `~> 2.1.0` is the suggested working version.
 
 ```ruby
 gem 'lite-command'
@@ -48,7 +48,8 @@ Or install it yourself as:
 
 ## Setup
 
-Defining a command is as simple as adding a call method to a command object (required).
+Defining a command is as simple as inheriting the base class and
+adding a `call` method to a command object (required).
 
 ```ruby
 class CalculatePower < Lite::Command::Base
@@ -133,7 +134,7 @@ class CalculatePower < Lite::Command::Base
 end
 
 CalculatePower.call!(...)
-#=> raises CalculatePower::Fault
+#=> raises CalculatePower::Failure
 ```
 
 ## Context
@@ -142,6 +143,9 @@ Accessing the call arguments can be done through its internal context.
 It can be used as internal storage to be accessed by it self and any
 of its children commands.
 
+> [!NOTE]
+> Attributes that do **NOT** exist on the context will return `nil`.
+
 ```ruby
 class CalculatePower < Lite::Command::Base
 
@@ -152,8 +156,9 @@ class CalculatePower < Lite::Command::Base
 
 end
 
-command = CalculatePower.call(a: 2, b: 3)
-command.context.result #=> 8
+cmd = CalculatePower.call(a: 2, b: 3)
+cmd.context.result #=> 8
+cmd.ctx.fake       #=> nil
 ```
 
 ### Attributes
@@ -167,7 +172,7 @@ method which automatically delegates to `context`.
 | `from`     | Symbol, String | `:context` | The object containing the attribute. |
 | `types`    | Symbol, String, Array, Proc | | The allowed class types of the attribute value. |
 | `required` | Symbol, String, Boolean, Proc | `false` | The attribute must be passed to the context or delegatable (no matter the value). |
-| `filled`   | Symbol, String, Boolean, Proc | `false` | The attribute value must be not be `nil`. |
+| `filled`   | Symbol, String, Boolean, Proc, Hash | `false` | The attribute value must be not be `nil`. Prevent empty values using `{ empty: false }` |
 
 > [!NOTE]
 > If optioned with some similar to `filled: true, types: [String, NilClass]`
@@ -180,7 +185,7 @@ class CalculatePower < Lite::Command::Base
 
   attribute :a, :b
   attribute :c, :d, from: :remote_storage, types: [Integer, Float]
-  attribute :x, :y, from: :local_storage, if: :signed_in?
+  attribute :x, :y, from: :local_storage, filled: { empty: false }, if: :signed_in?
 
   def call
     context.result =
@@ -202,20 +207,20 @@ class CalculatePower < Lite::Command::Base
 end
 
 # With valid options:
-storage = RemoteStorage.new(c: 2, d: 2, j: 99)
-command = CalculatePower.call(a: 2, b: 2, remote_storage: storage)
-command.status         #=> "success"
-command.context.result #=> 6
-
-# With invalid options
-command = CalculatePower.call
-command.status   #=> "invalid"
-command.reason   #=> "Invalid context attributes"
-command.metadata #=> {
-                 #=>   context: ["a is required", "remote_storage must be filled"],
-                 #=>   remote_storage: ["d type invalid"]
-                 #=>   local_storage: ["is not defined or an attribute"]
-                 #=> }
+rs  = RemoteStorage.new(c: 2, d: 2, j: 99)
+cmd = CalculatePower.call(a: 2, b: 2, remote_storage: rs)
+cmd.status         #=> "success"
+cmd.context.result #=> 6
+
+# With invalid options:
+cmd = CalculatePower.call
+cmd.status   #=> "invalid"
+cmd.reason   #=> "Invalid context attributes"
+cmd.metadata #=> {
+             #=>   context: ["a is required", "remote_storage must be filled"],
+             #=>   remote_storage: ["d type invalid"]
+             #=>   local_storage: ["is not defined or an attribute"]
+             #=> }
 ```
 
 ## States
@@ -232,18 +237,16 @@ command.metadata #=> {
 > States are automatically transitioned and should **NEVER** be altered manually.
 
 ```ruby
-class CalculatePower < Lite::Command::Base
+cmd = CalculatePower.call
+cmd.state        #=> "complete"
 
-  def call
-    # ...
-  end
-
-end
+cmd.pending?     #=> false
+cmd.executing?   #=> false
+cmd.complete?    #=> true
+cmd.interrupted? #=> false
 
-command = CalculatePower.call(a: 1, b: 3)
-command.state     #=> "executed"
-command.pending?  #=> false
-command.executed? #=> false
+# `complete` or `interrupted`
+cmd.executed?
 ```
 
 ## Statuses
@@ -285,14 +288,25 @@ class CalculatePower < Lite::Command::Base
 
 end
 
-command = CalculatePower.call(a: 1, b: 3)
-command.ctx.result #=> nil
-command.status     #=> "noop"
-command.reason     #=> "Anything to the power of 1 is 1"
-command.metadata   #=> { i18n: "some.key" }
-command.invalid?   #=> false
-command.noop?      #=> true
-command.noop?("Anything to the power of 1 is 1") #=> true
+cmd = CalculatePower.call(a: 1, b: 3)
+cmd.status   #=> "noop"
+cmd.reason   #=> "Anything to the power of 1 is 1"
+cmd.metadata #=> { i18n: "some.key" }
+
+cmd.success? #=> false
+cmd.noop?    #=> true
+cmd.noop?("Other reason") #=> false
+cmd.invalid? #=> false
+cmd.failure? #=> false
+cmd.error?   #=> false
+
+# `success` or `noop`
+cmd.ok?      #=> true
+cmd.ok?("Other reason") #=> false
+
+# NOT `success`
+cmd.fault?   #=> true
+cmd.fault?("Other reason") #=> false
 ```
 
 ## Callbacks
@@ -423,7 +437,8 @@ that it gains automated indexing and the parents `cmd_id`.
 class CalculatePower < Lite::Command::Base
 
   def call
-    CalculateSqrt.call(context.merge!(some_other: "required value"))
+    context.merge!(some_other: "required value")
+    CalculateSqrt.call(context)
   end
 
 end
@@ -434,7 +449,8 @@ end
 Throwing faults allows you to bubble up child faults up to the parent.
 Use it to create branches within your logic and create clean tracing
 of your command results. You can use `throw!` as a catch-all or any
-of the bang status method `failure!`.
+of the bang status method `failure!`. Any `reason` and `metadata` will
+be bubbled up from the original fault.
 
 ```ruby
 class CalculatePower < Lite::Command::Base
@@ -443,10 +459,10 @@ class CalculatePower < Lite::Command::Base
     command = CalculateSqrt.call(context.merge!(some_other: "required value"))
 
     if command.noop?("Sqrt of 1 is 1")
-      # Manually throw any fault you want
+      # Manually throw a specific fault
       invalid!(command)
     elsif command.fault?
-      # Automatically throws a matching fault type
+      # Automatically throws a matching fault
       throw!(command)
     else
       # Success, do nothing
@@ -467,6 +483,10 @@ This is useful for composing multiple steps into one call.
 > so its no different than just passing the context forward. To change
 > this behavior, just override the `ok?` method with you logic, eg: just `success`
 
+> [!IMPORTANT]
+> Do **NOT** define a call method in this class. The sequence logic is
+> automatically defined by the sequence class.
+
 ```ruby
 class ProcessCheckout < Lite::Command::Sequence
 
@@ -477,8 +497,7 @@ class ProcessCheckout < Lite::Command::Sequence
   step SendConfirmationEmail, SendConfirmationText
   step NotifyWarehouse, unless: proc { ctx.invoice.fullfilled_by_amazon? }
 
-  # Do NOT set a call method.
-  # Its defined by Lite::Command::Sequence
+  # Do NOT define a call method.
 
   private
 
@@ -488,7 +507,7 @@ class ProcessCheckout < Lite::Command::Sequence
 
 end
 
-sequence = ProcessCheckout.call(...)
+seq = ProcessCheckout.call(...)
 # <ProcessCheckout ...>
 ```
 

data/lib/lite/command/attribute.rb

@@ -4,12 +4,10 @@ module Lite
   module Command
     class Attribute
 
-      # TODO: allow procs
+      attr_accessor :command
+      attr_reader :method_name, :options, :errors
 
-      attr_reader :command, :method_name, :options, :errors
-
-      def initialize(command, method_name, options)
-        @command = command
+      def initialize(method_name, options)
         @method_name = method_name
         @options = options
         @errors = []
@@ -36,7 +34,7 @@ module Lite
           t = Array(Utils.call(command, options[:types]))
 
           if filled?
-            t - [NilClass]
+            t.uniq - [NilClass]
           else
             t | [NilClass]
           end
@@ -84,9 +82,17 @@ module Lite
         @errors << "#{method_name} type invalid"
       end
 
+      def empty?
+        r = Utils.try(options[:filled], :[], :empty)
+        return if r.nil? || r == true
+        return unless value.respond_to?(:empty?)
+
+        value.empty?
+      end
+
       def validate_attribute_filled!
         return unless filled?
-        return unless value.nil?
+        return unless value.nil? || empty?
 
         @errors << "#{method_name} must be filled"
       end

data/lib/lite/command/attribute_validator.rb

@@ -12,15 +12,14 @@ module Lite
 
       def attributes
         @attributes ||=
-          command.class.attributes.map do |method_name, options|
-            Lite::Command::Attribute.new(command, method_name, options)
+          command.class.attributes.map do |_method_name, attribute|
+            attribute.tap { |a| a.command = command }
           end
       end
 
       def errors
         @errors ||= attributes.each_with_object({}) do |attribute, h|
-          attribute.validate!
-          next if attribute.valid?
+          next if attribute.tap(&:validate!).valid?
 
           h[attribute.from] ||= []
           h[attribute.from] = h[attribute.from] | attribute.errors

data/lib/lite/command/internals/call.rb

@@ -86,7 +86,6 @@ module Lite
           # eg: invalid!("idk") or failure!(fault) or error!("idk", { error_key: "some.error" })
           define_method(:"#{f}!") do |object, metadata = nil|
             fault(object, f, metadata)
-
             raise Lite::Command::Fault.build(f.capitalize, self, object, dynamic: raise_dynamic_faults?)
           end
         end

data/lib/lite/command/internals/context.rb

@@ -13,13 +13,13 @@ module Lite
 
           def attribute(*args, **options)
             args.each do |method_name|
-              attributes[method_name] = options
+              attribute = Lite::Command::Attribute.new(method_name, options)
+              attributes[method_name] = attribute
 
               define_method(method_name) do
                 ivar = :"@#{method_name}"
                 return instance_variable_get(ivar) if instance_variable_defined?(ivar)
 
-                attribute = Lite::Command::Attribute.new(self, method_name, options)
                 instance_variable_set(ivar, attribute.value)
               end
             end

data/lib/lite/command/internals/execute.rb

@@ -72,6 +72,7 @@ module Lite
         rescue StandardError => e
           fault(e, ERROR, metadata) unless e.is_a?(Lite::Command::Fault)
           after_execution
+          Utils.hook(self, :"on_#{status}", e)
           raise(e)
         else
           Utils.hook(self, :"on_#{state}")

data/lib/lite/command/utils.rb

@@ -16,13 +16,13 @@ module Lite
         try(object, method_name, *args, include_private: true)
       end
 
-      def call(object, method_name_or_proc)
-        if method_name_or_proc.is_a?(Symbol) || method_name_or_proc.is_a?(String)
-          object.send(method_name_or_proc)
-        elsif method_name_or_proc.is_a?(Proc)
-          object.instance_eval(&method_name_or_proc)
+      def call(object, argument)
+        if argument.is_a?(Symbol) || argument.is_a?(String)
+          object.send(argument)
+        elsif argument.is_a?(Proc)
+          object.instance_eval(&argument)
         else
-          method_name_or_proc
+          argument
         end
       end
 

data/lib/lite/command/version.rb

@@ -3,7 +3,7 @@
 module Lite
   module Command
 
-    VERSION = "2.1.0"
+    VERSION = "2.1.2"
 
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lite-command
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.1.2
 platform: ruby
 authors:
 - Juan Gomez
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-10-06 00:00:00.000000000 Z
+date: 2024-10-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ostruct
@@ -173,10 +173,10 @@ extra_rdoc_files: []
 files:
 - ".fasterer.yml"
 - ".gitattributes"
+- ".github/workflows/ci.yml"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
-- ".travis.yml"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
@@ -227,7 +227,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.20
+rubygems_version: 3.5.21
 signing_key:
 specification_version: 4
 summary: Ruby Command based framework (aka service objects)

data/.travis.yml

@@ -1,25 +0,0 @@
-sudo: false
-language: ruby
-cache: bundler
-rvm:
-- 2.5
-- 2.6
-- 2.7
-- ruby-head
-matrix:
-  fast_finish: true
-  allow_failures:
-  - rvm: ruby-head
-before_install:
-- gem update --system
-- gem install bundler
-install:
-- bundle install --jobs=3 --retry=3
-script:
-- bundle exec rspec
-- bundle exec rubocop
-- bundle exec fasterer
-notifications:
-  email: false
-  slack:
-    secure: 2PptrBf+yl8evd/WA4XKg0tzJqSdEn5TaAhuHR90o5X6Rd0MA4SES+QZQn9A81CPuJk//V8Dur8NQQzrcAivVOsmC+JbIHZV1MS8v32Uvoy28Vr8omAne4Ec3so6rXCIMniREGcHtKeXHdNYO61VZPPjgxd7RTwajvTC7KS0ViuKBPct+hq+WfJmX6Xp2vxTHImNVurExBrFZkJyPtV+UG1tJ6mB+kF8MQ1+t3ZBtU4+6eVviADYi7FBEeP0j9gdKBCzU7aPoE+XLMWcP0tI9ibaP9crEMKi05JNDLzm5f6PGvGJWEQSCeh3CxNhaEF7eog3BAw6mUXkKI0hvFfrZeyG+VkDU6T9rAG8u55BrREi4mRNJl0c0rS2J45bFRmYOlvDNn9xrhMkkfFn8SMX3etYJYqHNBxdF2TX4SzpDrshd3hcm2btmkThn/Ua/mYUWs9OF3O/ZSu0zB+/g83zrAsjMyfqJ1PE5ZiiMD2Rjrzb/fyYcsNeVhncwRdse9LtJRqz1KpOh/r5LBrWfRRCQwlVNwMtBdFxQ7Ytl9dz/dfJmGKgM8zsdJdI6ZyV+lwa0jPaql6Y8wXjox1wwN3IRCyvoVsgxmiQAV8jnWD2lf6I/Ea5yXCImGluuRAyRrAizElXGBNubhAVtQwQinHWfaYO+mJElScBwrxTVXuzQUI=