trailblazer-option 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6002d9d525ee513b07f18ba89480e2a69be11892664186e8020c085e0286bf2
-  data.tar.gz: af25382707b80a01760a204861da7860ce4f60cd9a534b3015278de344cc8236
+  metadata.gz: a0d62e8bc54ba2cf87c8f8039a753a23ec1d1ae86c54345c44b049465ed6c7e4
+  data.tar.gz: 5a84e2737e097ac47fd952fdab0888413e77ef9586863eb25dfc7a4221bda2e4
 SHA512:
-  metadata.gz: 1b3cfd6578fd2faf2a4d5e8f0df117ce387c01868e95056c3e6c0c4217129495ffd80f50a7ba05a166fcdefeab58931cccb5fbea845750b13c8b2e283044bc3d
-  data.tar.gz: fe6c2ce74b8ed5aac51ab0bc4fa773f2b8408f993667cb01299310806ed2d867c5d9724375dabc326d515107f79e59f6690522b02ee56fc68941364a87a08265
+  metadata.gz: 6bff90fce5bc96d842ddfc81c7ce281a6abf1a474a35f02513d0dd764c3506a612ee92f88f2bdb55cd4ec0e12811554bcfd36408760b0536694d524942d3f96f
+  data.tar.gz: 469819438960ec5e67ff5020543399c79b795e5632b9bc57ef836f3b62aa2a029521f8346ad233e0c9d655691b8908f3916d658b2cca6fe19ed8db5b6e219d4e

data/CHANGES.md

@@ -1,3 +1,7 @@
+# 0.1.2
+
+* Evaluate callable at compile time itself to improve performance.
+
 # 0.1.1
 
 * Don't pass empty `keyword_arguments` for ruby <= 2.6.

data/README.md

@@ -1 +1,62 @@
-# trailblazer-option
+# Trailblazer::Option
+
+_Dynamic options to evaluate at runtime._
+
+`Trailblazer::Option` is the one of the core concept behind `traiblazer-operation`'s [step API](https://trailblazer.to/2.1/docs/activity.html#activity-wiring-api), `reform`'s [populator API](https://trailblazer.to/2.1/docs/reform.html#reform-populators) etc. It makes us possible to accept any kind of callable objects at compile time and execute them at runtime.
+
+```ruby
+class Song::Create < Trailblazer::Operation
+  step Authorize				# Module callable
+  step :model					# Method callable
+  step ->(ctx, model:, **) { puts model }	# Proc callable
+end
+```
+
+This gem is a replacement over [declarative-option](https://github.com/apotonick/declarative-option) and has been extracted out from [trailblazer-context](https://github.com/trailblazer/trailblazer-context) by identifying common callable patterns.
+
+# Option
+
+`Trailblazer::Option()` accepts `:symbol`, `lambda` and any other type of `callable` as an argument. It will be wrapped accordingly to make an executable, so you can call the value at runtime to evaluate it.
+
+When passing in a `:symbol`, this will be treated as a method that's called on the given `exec_context`.
+
+```ruby
+option = Trailblazer::Option(:object_id)
+option.(exec_context: Object.new) #=> 2354383
+```
+
+Same with objects responding to `.call` or `#call` method.
+
+```ruby
+class CallMe
+  def self.call(*args, message:, **options)
+    message
+  end
+end
+
+option = Trailblazer::Option(CallMe)
+option.(*args, keyword_arguments: { message: "hello!" }, exec_context: nil) => "hello!"
+```
+
+Notice the usage of `keyword_arguments` while calling an `Option`. This is because keyword arguments needs to be forwarded separately in order for them to be [compatible](https://www.ruby-lang.org/en/news/2019/12/12/separation-of-positional-and-keyword-arguments-in-ruby-3-0/) with ruby 2.7+.
+
+And of course, passing lambdas. They gets executed within given `exec_context` when set.
+
+```ruby
+option = Trailblazer::Option( -> { object_id } )
+option.(exec_context: Object.new) #=> 1234567
+```
+
+# Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'trailblazer-option'
+```
+
+# Copyright
+
+Copyright (c) 2017-2021 TRAILBLAZER GmbH.
+
+`trailblazer-option` is released under the [MIT License](http://www.opensource.org/licenses/MIT).

data/lib/trailblazer/option/version.rb

@@ -1,5 +1,5 @@
 module Trailblazer
   class Option
-    VERSION = '0.1.1'
+    VERSION = '0.1.2'
   end
 end

data/lib/trailblazer/option.rb

@@ -36,24 +36,18 @@ module Trailblazer
       call!(exec_context.method(value), *args, **options, &block)
     end
 
-    # Choose appropriate evaluator and forward all arguments.
-    # @private
-    def self.evaluator(value, *args, **options, &block)
+    # Generic builder for a callable "option".
+    # @param call_implementation [Class, Module] implements the process of calling the proc
+    #   while passing arguments/options to it in a specific style (e.g. kw args, step interface).
+    # @return [Proc] when called, this proc will evaluate its option (at run-time).
+    def self.build(value)
       evaluate = case value
                  when Symbol then  method(:evaluate_method)
                  when Proc   then  method(:evaluate_proc)
                  else              method(:evaluate_callable)
                  end
 
-      evaluate.(value, *args, **options, &block)
-    end
-
-    # Generic builder for a callable "option".
-    # @param call_implementation [Class, Module] implements the process of calling the proc
-    #   while passing arguments/options to it in a specific style (e.g. kw args, step interface).
-    # @return [Proc] when called, this proc will evaluate its option (at run-time).
-    def self.build(value)
-      ->(*args, **options, &block) { evaluator(value, *args, **options, &block) }
+      ->(*args, **options, &block) { evaluate.(value, *args, **options, &block) }
     end
   end
 

data/test/docs/option_test.rb

@@ -0,0 +1,26 @@
+require "test_helper"
+
+class DocsOptionTest < Minitest::Spec
+  it do
+    #:method
+    option = Trailblazer::Option(:object_id)
+    option.(exec_context: Object.new) # => 1234567
+    #:method end
+
+    #:lambda
+    option = Trailblazer::Option(-> { object_id })
+    option.(exec_context: Object.new) # => 1234567
+    #:lambda end
+
+    #:module
+    class CallMe
+      def self.call(message:, **options)
+        message
+      end
+    end
+
+    option = Trailblazer::Option(CallMe)
+    option.(keyword_arguments: { message: "hello!" }, exec_context: nil) # => "hello!"
+    #:module end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trailblazer-option
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Nick Sutterer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-04-13 00:00:00.000000000 Z
+date: 2021-11-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -72,6 +72,7 @@ files:
 - lib/trailblazer-option.rb
 - lib/trailblazer/option.rb
 - lib/trailblazer/option/version.rb
+- test/docs/option_test.rb
 - test/option_test.rb
 - test/test_helper.rb
 - trailblazer-option.gemspec
@@ -99,5 +100,6 @@ signing_key:
 specification_version: 4
 summary: Callable patterns for options in Trailblazer
 test_files:
+- test/docs/option_test.rb
 - test/option_test.rb
 - test/test_helper.rb