trailblazer-context 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f6c3c7ff9c8b061c5ac0d5aca954f03cd1b5ff0bf286aa787ede12f1e187890
-  data.tar.gz: 0fdc45ffab9316c7799f2ce59f54c6409305cf91fa01349d30d026eac998c188
+  metadata.gz: f2f68ea3324607256a507718188b38dcb7d0252f17bf49221b97b5e62be4d252
+  data.tar.gz: 6841b846db299f4c21352f03703c3b8780539e2eb59efbadf0bd1ecd780bb0d8
 SHA512:
-  metadata.gz: 2c9f349028afca126e1961e50ebb0ff661a5fe5a0e2573108c9c79f762694cdb03c6914beca4eec4c5b3b25aecae03d4706c47c84854d0ebb57b6e8a42ec279f
-  data.tar.gz: 1fba9db52f9e3680cccb3b89624c8a159bbd144fbd0b86b3a71972ea1feff96978b82867c976a568aec709b09d0fe859d173a1a813fa5747cb42d179bf6c7520
+  metadata.gz: d1ec16cbdba1cfeca1f3820e188dc5c8b449ff0295ee8849f5509297123b5c8b5046a9265206dff83051457e42aa7a7771387c82a4dfb5da6be9b2d93387b3aa
+  data.tar.gz: ee014562e35ad36355a8e62f18b8e8c2e497c86014aabac143ef308099e1f79f0b740d3f3e78fdeb0d9e5155b440ddb31e7f945da02fd48fc42eba1d7197f681

data/.github/workflows/ci.yml

@@ -0,0 +1,17 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        # Due to https://github.com/actions/runner/issues/849, we have to use quotes for '3.0'
+        ruby: [2.5, 2.6, 2.7, '3.0', head, jruby, jruby-head]
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - run: bundle exec rake

data/.gitignore

@@ -1,5 +1,6 @@
 *.gem
 *.rbc
+*.swp
 /.config
 /coverage/
 /InstalledFiles

data/CHANGES.md

@@ -1,3 +1,43 @@
+# 0.5.0
+
+* Extracted `Option` into its own repository, `trailblazer-option` ✨
+
+# 0.4.0
+
+* Ready for Ruby 3.0. :heart:
+* Remove `Option::KW`, after many years it's been superseded by the original `Trailblazer::Option`.
+
+    To achieve an invocation such as
+
+    ```ruby
+    Option::KW(proc).(ctx, another_positional_arg, **circuit_options)
+    ```
+
+    you can use the new `:keyword_arguments` options.
+
+    ```ruby
+    Option(proc).(ctx, another_positional_arg, keyword_arguments: ctx.to_hash, **circuit_options)
+    ```
+
+    This way, no more guessing is happening about what positional arg is the actual `circuit_options`.
+
+# 0.3.3
+
+* Remove an unsolicited `puts`.
+
+# 0.3.2
+
+* Relax gem dependency: `hashie` >= 3.0.
+
+# 0.3.1
+
+* Even though this is a patch version, but it contains major changes.
+* `to_hash` speed improvement - Same-ish as `Hash#to_hash`.
+* Maintains replica for faster access and copy actions.
+* Support all other `Hash` features (find, dig, collect etc) on `ctx` object.
+* Namespace context related options within `flow_options`. (`{ flow_options: { context_options: { aliases: {}, ** } } }`).
+* Add `Trailblazer::Context()` API with standard default container & replica class.
+
 # 0.3.0
 * Add support for ruby 2.7
 * Drop support for ruby 2.0

data/README.md

@@ -5,5 +5,4 @@ _Argument-specific data structures for Trailblazer._
 This gem provides data structures needed across `Activity`, `Workflow` and `Operation`, such as the following.
 
 * `Trailblazer::Context` implements the so-called `options` hash that is passed between steps and implements the keyword arguments.
-* `Trailblazer::Option` is often used to wrap an option at compile-time and `call` it at runtime, which allows to have the common `-> ()`, `:method` or `Callable` pattern used for most options.
 * `Trailblazer::ContainerChain` to implement chained lookups of properties and allow including containers such as `Dry::Container` in this chain. This is experimental.

data/Rakefile

@@ -7,4 +7,10 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList["test/*_test.rb"]
 end
 
+Rake::TestTask.new(:benchmark) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/benchmark/*_test.rb"]
+end
+
 task default: %i[test]

data/lib/trailblazer/context.rb

@@ -1,104 +1,33 @@
-require "trailblazer/option"
 # TODO: mark/make all but mutable_options as frozen.
-# The idea of Skill is to have a generic, ordered read/write interface that
+# The idea of Context is to have a generic, ordered read/write interface that
 # collects mutable runtime-computed data while providing access to compile-time
 # information.
 # The runtime-data takes precedence over the class data.
-#
-# notes
-# a context is a ContainerChain with two elements (when reading)
 module Trailblazer
   # Holds local options (aka `mutable_options`) and "original" options from the "outer"
   # activity (aka wrapped_options).
-
   # only public creator: Build
   # :data object:
-  class Context
-    # NOTE: In the future, we might look up the Context to use in the ctx.
-    #       The demanding signature is for forward-compat.
-    # @private
-    def self.for(wrapped_options, (ctx, flow_options), **circuit_options) # TODO: remove
-      implementation.build(wrapped_options, {}, [ctx, flow_options], circuit_options)
-    end
-
-    def self.for_circuit(wrapped_options, mutable_options, (ctx, flow_options), **circuit_options)
-      context_class = flow_options[:context_class] || implementation # Context::IndifferentAccess
+  module Context
+    autoload :Container, "trailblazer/context/container"
 
-      context_class.build(wrapped_options, mutable_options, [ctx, flow_options], circuit_options)
+    module Store
+      autoload :IndifferentAccess, "trailblazer/context/store/indifferent_access"
     end
 
-    # @public
-    def self.build(wrapped_options, *)
-      new(wrapped_options)
-    end
-
-    # I hate globals, but currently this is the only easy way for setting the implementation.
-    def self.implementation
-      IndifferentAccess
-    end
-
-    def initialize(wrapped_options, mutable_options, *)
-      @wrapped_options = wrapped_options
-      @mutable_options = mutable_options
-      # TODO: wrapped_options should be optimized for lookups here since
-      # it could also be a Context instance, but should be a ContainerChain.
-    end
-
-    def [](name)
-      # ContainerChain.find( [@mutable_options, @wrapped_options], name )
-
-      # in 99.9% or cases @mutable_options will be a Hash, and these are already optimized for lookups.
-      # it's up to the ContainerChain to optimize itself.
-      return @mutable_options[name] if @mutable_options.key?(name)
-      @wrapped_options[name]
-    end
+    module_function
 
-    # TODO: use ContainerChain.find here for a generic optimization
-    #
-    # the version here is about 4x faster for now.
-    def key?(name)
-      # ContainerChain.find( [@mutable_options, @wrapped_options], name )
-      @mutable_options.key?(name) || @wrapped_options.key?(name)
+    def for_circuit(wrapped_options, mutable_options, (_, flow_options), **)
+      build(wrapped_options, mutable_options, **flow_options.fetch(:context_options))
     end
 
-    def []=(name, value)
-      @mutable_options[name] = value
-    end
-
-    # @private
-    def merge(hash)
-      original, mutable_options = decompose
-
-      self.class.new(original, mutable_options.merge(hash))
-    end
-
-    # Return the Context's two components. Used when computing the new output for
-    # the next activity.
-    def decompose
-      [@wrapped_options, @mutable_options]
-    end
-
-    def keys
-      @mutable_options.keys + @wrapped_options.keys # FIXME.
-    end
-
-    # TODO: maybe we shouldn't allow to_hash from context?
-    # TODO: massive performance bottleneck. also, we could already "know" here what keys the
-    # transformation wants.
-    # FIXME: ToKeywordArguments()
-    def to_hash
-      {}.tap do |hash|
-        # the "key" here is to call to_hash on all containers.
-        [@wrapped_options.to_hash, @mutable_options.to_hash].each do |options|
-          options.each { |k, v| hash[k.to_sym] = v }
-        end
-      end
+    def build(wrapped_options, mutable_options, container_class:, **context_options)
+      container_class.new(wrapped_options, mutable_options, **context_options)
     end
   end
 
-  def self.Context(wrapped_options, mutable_options = {})
-    Context.new(wrapped_options, mutable_options)
+  def self.Context(wrapped_options, mutable_options = {}, context_options = nil)
+    defaults = { container_class: Context::Container, replica_class: Context::Store::IndifferentAccess }
+    Context.build(wrapped_options, mutable_options, **defaults.merge( Hash(context_options) ))
   end
 end
-
-require "trailblazer/context/indifferent_access"

data/lib/trailblazer/context/container.rb

@@ -0,0 +1,100 @@
+require "forwardable"
+
+module Trailblazer
+  module Context
+    class Container
+      autoload :WithAliases, "trailblazer/context/container/with_aliases"
+
+      class UseWithAliases < RuntimeError
+        def message
+          %{Pass `Trailblazer::Context::Container::WithAliases` as `container_class` while defining `aliases`}
+        end
+      end
+
+      def initialize(wrapped_options, mutable_options, replica_class:, aliases: nil, **)
+        raise UseWithAliases if aliases
+
+        @wrapped_options  = wrapped_options
+        @mutable_options  = mutable_options
+        @replica_class    = replica_class
+
+        @replica = initialize_replica_store
+      end
+
+      # Return the Context's two components. Used when computing the new output for
+      # the next activity.
+      def decompose
+        [@wrapped_options, @mutable_options]
+      end
+
+      def inspect
+        %{#<Trailblazer::Context::Container wrapped_options=#{@wrapped_options} mutable_options=#{@mutable_options}>}
+      end
+      alias_method :to_s, :inspect
+
+      private def initialize_replica_store
+        @replica_class.new([ @wrapped_options, @mutable_options ])
+      end
+
+      # Some common methods made available directly in Context::Container for
+      # performance tuning, extensions and to avoid `@replica` delegations.
+      module CommonMethods
+        def [](key)
+          @replica[key]
+        end
+
+        def []=(key, value)
+          @replica[key] = value
+          @mutable_options[key] = value
+        end
+        alias_method :store, :[]=
+
+        def delete(key)
+          @replica.delete(key)
+          @mutable_options.delete(key)
+        end
+
+        def merge(other_hash)
+          self.class.new(
+            @wrapped_options,
+            @mutable_options.merge(other_hash),
+            replica_class: @replica_class,
+          )
+        end
+
+        def fetch(key, default = nil, &block)
+          @replica.fetch(key, default, &block)
+        end
+
+        def keys; @replica.keys; end
+
+        def key?(key); @replica.key?(key); end
+
+        def values; @replica.values; end
+
+        def value?(value); @replica.value?(value); end
+
+        def to_hash; @replica.to_hash; end
+
+        def each(&block); @replica.each(&block); end
+        include Enumerable
+      end
+
+      # Additional methods being forwarded on Context::Container
+      # NOTE: def_delegated method calls incurs additional cost
+      # compared to actual method defination calls.
+      # https://github.com/JuanitoFatas/fast-ruby/pull/182
+      module Delegations
+        extend Forwardable
+        def_delegators :@replica,
+          :default, :default=, :default_proc, :default_proc=,
+          :fetch_values, :index, :dig, :slice,
+          :key, :each_key,
+          :each_value, :values_at
+      end
+
+      include CommonMethods
+      extend Delegations
+    end
+  end
+end

data/lib/trailblazer/context/container/with_aliases.rb

@@ -0,0 +1,102 @@
+module Trailblazer
+  module Context
+    class Container
+      # Extension to replace Context::Container writers with aliased writers.
+      # It'll mutate the well known `@mutable_options` with only original keys and
+      # `@replica` with both orignal and aliased keys
+      class WithAliases < Container
+        def initialize(wrapped_options, mutable_options, aliases:, replica_class:, **)
+          @wrapped_options  = wrapped_options
+          @mutable_options  = mutable_options
+
+          # { "contract.default" => :contract, "result.default" => :result }
+          @aliases          = aliases
+
+          @replica_class    = replica_class
+          @replica          = initialize_replica_store
+        end
+
+        def inspect
+          %{#<Trailblazer::Context::Container::WithAliases wrapped_options=#{@wrapped_options} mutable_options=#{@mutable_options} aliases=#{@aliases}>}
+        end
+
+        # @public
+        def aliased_writer(key, value)
+          _key, _alias = alias_mapping_for(key)
+
+          @mutable_options[_key] = value
+          @replica[_key]         = value
+          @replica[_alias]       = value if _alias
+        end
+        alias_method :[]=, :aliased_writer
+
+        # @public
+        def aliased_delete(key)
+          _key, _alias = alias_mapping_for(key)
+
+          @mutable_options.delete(_key)
+          @replica.delete(_key)
+          @replica.delete(_alias) if _alias
+        end
+        alias_method :delete, :aliased_delete
+
+        # @public
+        def aliased_merge(other_hash)
+          # other_hash could have aliases and we don't want to store them in @mutable_options.
+          _other_hash = replace_aliases_with_original_keys(other_hash)
+
+          options = { aliases: @aliases, replica_class: @replica_class }
+          self.class.new(@wrapped_options, @mutable_options.merge(_other_hash), **options)
+        end
+        alias_method :merge, :aliased_merge
+
+        # Returns key and it's mapped alias. `key` could be an alias too.
+        #
+        # aliases => { "contract.default" => :contract, "result.default"=>:result }
+        # key, _alias = alias_mapping_for(:contract)
+        # key, _alias = alias_mapping_for("contract.default")
+        #
+        # @public
+        def alias_mapping_for(key)
+          # when key has an alias
+          return [ key, @aliases[key] ] if @aliases.key?(key)
+
+          # when key is an alias
+          return [ @aliases.key(key), key ] if @aliases.value?(key)
+
+          # when there is no alias
+          return [ key, nil ]
+        end
+
+        private
+
+        # Maintain aliases in `@replica` to make ctx actions faster™
+        def initialize_replica_store
+          replica = @replica_class.new([ @wrapped_options, @mutable_options ])
+
+          @aliases.each do |original_key, _alias|
+            replica[_alias] = replica[original_key] if replica.key?(original_key)
+          end
+
+          replica
+        end
+
+        # Replace aliases from `hash` with their orignal keys.
+        # This is used while doing a `merge` which initializes new Container
+        # with original keys and their aliases.
+        def replace_aliases_with_original_keys(hash)
+          # DISCUSS: Better way to check for alias presence in `hash`
+          return hash unless (hash.keys & @aliases.values).any?
+
+          _hash = hash.dup
+
+          @aliases.each do |original_key, _alias|
+            _hash[original_key] = _hash.delete(_alias) if _hash.key?(_alias)
+          end
+
+          return _hash
+        end 
+      end
+    end
+  end
+end

data/lib/trailblazer/context/store/indifferent_access.rb

@@ -0,0 +1,36 @@
+require "hashie"
+
+module Trailblazer
+  module Context
+    module Store
+      # Simple yet indifferently accessible hash store, used as replica in Context::Container.
+      # It maintains cache for multiple hashes (wrapped_options, mutable_options etc).
+      class IndifferentAccess < Hash
+        include Hashie::Extensions::IndifferentAccess
+
+        def initialize(hashes)
+          hashes.each do |hash|
+            hash.each do |key, value|
+              self[key] = value
+            end
+          end
+        end
+
+        # Override of Hashie::Extensions::IndifferentAccess#indifferent_value
+        # to not do deep indifferent access conversion.
+        # DISCUSS: Should we make this configurable ?
+        def indifferent_value(value)
+          value
+        end
+
+        # Override of Hashie::Extensions::IndifferentAccess#convert_key
+        # to store keys as Symbol by default instead of String.
+        # Why ? We need to pass `ctx` as keyword arguments most of the time.
+        def convert_key(key)
+          return key if Symbol === key 
+          String === key ? key.to_sym : key
+        end
+      end
+    end
+  end
+end