plumb 0.0.14 → 0.0.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bfaf49dcfcb3b25cc3dbca406efe1c666284df83466ee87c5b7faf63d613ab04
-  data.tar.gz: 7a95598acd4e07180d68b17a6b72d3fddf00aa293503bdc353a37c585dcc95c0
+  metadata.gz: 104313a59a2f9187f582058b8f0f3c6dce43763079518d68fde511aef6112400
+  data.tar.gz: 4fc765c09d840145ebf5777cfd4e326f3705db5cfda8ee5324c5f6f4f81e0070
 SHA512:
-  metadata.gz: 44fb44f7f2c6650ad1dc9a68b7945200bd87df874246ee0785d11e4fc936db89a552dca473753303e34cbecb8764fc2272d9c6829427664175bfaba1fe876623
-  data.tar.gz: 6b27b375b6b2df1188ec821a918325a9ff97bd0b35c65ee16d4826ef8b018ee497f18e461a2e472281f50a3754c835347a49943dd3fdf0dac1aa949aea3b3145
+  metadata.gz: 2ca83f0ed1b4fbb2a83e11ff05bded28ed99550de9bfbec2d20d79943d886209c6b4cabeb2055857e24e60748642f0f7b541dcf5dc433107073772b085c5025a
+  data.tar.gz: 9d7b79dc0509f481730331bd3e65a1b85378d3609279b6c575ec8d77d8e786ccbe33b8dd54b0abfa826df06454793b235c1f8086a581c9a143359899cebb0318

data/README.md

@@ -232,6 +232,7 @@ You can see more use cases in [the examples directory](https://github.com/ismasa
 * `Types::Numeric`
 * `Types::String`
 * `Types::Hash`
+* `Types::SymbolizedHash`
 * `Types::UUID::V4`
 * `Types::Email`
 * `Types::Date`
@@ -838,7 +839,19 @@ User.parse(name: 'Joe', age: 40) # => { name: 'Joe', age: 40 }
 User.parse(name: 'Joe', age: 'nope') # => { name: 'Joe' }
 ```
 
-### Hash maps
+### `Types::SymbolizedHash`
+
+This type turns a hash's keys into symbols by calling `#to_sym` on them, and returning a new Hash.
+
+```ruby
+# Make sure to symbolize keys first
+type = Types::SymbolizedHash > Types::Hash[name: String, age: Integer]
+type.parse('name' => 'Joe', 'age' => 20) # {name: 'Joe', age: 20}
+```
+
+
+
+###  maps
 
 You can also use Hash syntax to define a hash map with specific types for all keys and values:
 
@@ -1177,7 +1190,51 @@ Using `attribute?` allows for optional attributes. If the attribute is not prese
 attribute? :company, Company
 ```
 
+#### Before steps, symbolizing keys
+
+The optional `.step` helper adds arbitrary Plumb steps to a Data constructor's internal pipeline.
+
+This pipeline processes input data when initialising a Data instance.
+
+This example adds the built-in `Types::SymbolizedHash` type to make sure struct inputs are symbolised before processing.
+
+```ruby
+class Person < Types::Data
+  step Types::SymbolizedHash
+  
+  attribute :name, String
+  attribute :age, Integer
+end
+
+# String keys will be symbolised now
+person = Person.new('name' => 'Joe', 'age' => 40)
+person.name # 'Joe'
+person.to_h # => { name: 'Joe', age: 40 }
+```
+
+Inline blocks can be registered as steps
+
+```ruby
+class Person < Types::Data
+  # upcase all values
+  step do |r|
+    upcased = r.value.transform_values(&:upcase)
+    r.valid upcased
+  end
+  
+  attribute :name, String
+  attribute :last_name, String
+end
+
+person = Person.new(name: 'joe', last_name: 'bloggs')
+person.name # => 'JOE'
+person.last_name # => 'BLOGGS'
+```
+
+A Data class steps are inherited to its child classes.
+
 #### Inheritance
+
 Data structs can inherit from other structs. This is useful for defining a base struct with common attributes.
 
 ```ruby

data/lib/plumb/attributes.rb

@@ -116,7 +116,7 @@ module Plumb
     attr_reader :errors, :attributes
 
     def initialize(attrs = {})
-      assign_attributes(attrs)
+      assign_attributes(self.class._pipeline.parse(attrs))
       freeze
     end
 
@@ -135,8 +135,8 @@ module Plumb
 
     def inspect
       %(#<#{self.class}:#{object_id} [#{valid? ? 'valid' : 'invalid'}] #{attributes.map do |k, v|
-                                                                           [k, v.inspect].join(':')
-                                                                         end.join(' ')}>)
+        [k, v.inspect].join(':')
+      end.join(' ')}>)
     end
 
     # @return [Hash]
@@ -175,11 +175,53 @@ module Plumb
     def prepare_attributes(attrs) = attrs
 
     module ClassMethods
+      def _set_pipeline(pl)
+        @_pipeline = pl
+      end
+
+      def _pipeline
+        @_pipeline || Plumb::Types::Any
+      end
+
+      # Add a step to the processing pipeline that runs before attribute validation.
+      # This allows you to transform or validate the input data before it's assigned to attributes.
+      #
+      # @param st [Plumb::Step, nil] A step object to add to the pipeline
+      # @param block [Proc, nil] A block to use as a step (if st is nil)
+      # @return [Class] Returns self for method chaining
+      #
+      # @example Transform input before validation
+      #   class Person
+      #     include Plumb::Attributes
+      #
+      #     step { |result| result.valid(result.value.transform_keys(&:to_sym)) }
+      #     attribute :name, Types::String
+      #   end
+      #
+      # @example Add custom validation
+      #   class Person
+      #     include Plumb::Attributes
+      #
+      #     step do |result|
+      #       if result.value[:name].nil?
+      #         result.invalid(errors: 'Name is required')
+      #       else
+      #         result
+      #       end
+      #     end
+      #     attribute :name, Types::String
+      #   end
+      def step(st = nil, &block)
+        @_pipeline = _pipeline >> (st || block)
+        self
+      end
+
       def _schema
         @_schema ||= HashClass.new
       end
 
       def inherited(subclass)
+        subclass._set_pipeline _pipeline
         _schema._schema.each do |key, type|
           subclass.attribute(key, type)
         end
@@ -220,7 +262,9 @@ module Plumb
       # attribute(:friends, [Person])
       #
       def attribute(name, type = Types::Any, writer: false, &block)
-        key = Key.wrap(name)
+        # Key accepts String or Symbol, with optional '?' suffix for optional keys
+        # for Data structs, we always convert to Symbol keys
+        key = Key.wrap(name, symbolize: true)
         name = key.to_sym
         type = Composable.wrap(type)
 

data/lib/plumb/hash_class.rb

@@ -113,7 +113,7 @@ module Plumb
       initial = {}
       initial = initial.merge(input) if @inclusive
       output = _schema.each.with_object(initial) do |(key, field), ret|
-        key_s = key.to_sym
+        key_s = key.to_key
         if input.key?(key_s)
           r = field.call(field_result.reset(input[key_s]))
           errors[key_s] = r.errors unless r.valid?

data/lib/plumb/key.rb

@@ -2,28 +2,30 @@
 
 module Plumb
   class Key
-    OPTIONAL_EXP = /(\w+)(\?)?$/
+    # OPTIONAL_EXP = /(\w+)(\?)?$/
+    OPTIONAL_EXP = /(?<word>[A-Za-z0-9_$]+)(?<qmark>\?)?/
 
-    def self.wrap(key)
-      key.is_a?(Key) ? key : new(key)
+    def self.wrap(key, symbolize: false)
+      key.is_a?(Key) ? key : new(key, symbolize:)
     end
 
-    attr_reader :to_sym, :node_name
+    attr_reader :to_key, :to_sym, :node_name
 
-    def initialize(key, optional: false)
-      key_s = key.to_s
-      match = OPTIONAL_EXP.match(key_s)
+    def initialize(key, optional: false, symbolize: false)
+      key_type = symbolize ? Symbol : key.class
+      match = OPTIONAL_EXP.match(key.to_s)
+      key = match[:word]
+      @to_key = key_type == Symbol ? key.to_sym : key
+      @to_sym = @to_key.to_sym
+      @optional = !match[:qmark].nil? ? true : optional
       @node_name = :key
-      @key = match[1]
-      @to_sym = @key.to_sym
-      @optional = !match[2].nil? ? true : optional
       freeze
     end
 
-    def to_s = @key
+    def to_s = @to_key.to_s
 
     def hash
-      @key.hash
+      @to_key.hash
     end
 
     def eql?(other)
@@ -35,7 +37,7 @@ module Plumb
     end
 
     def inspect
-      "#{@key}#{'?' if @optional}"
+      "#{@to_key}#{'?' if @optional}"
     end
   end
 end

data/lib/plumb/types.rb

@@ -155,6 +155,22 @@ module Plumb
     Date = Any[::Date]
     Time = Any[::Time]
 
+    # A type that recursively converts string keys to symbols in nested hashes.
+    # This is commonly used for normalizing payload data in commands and events.
+    #
+    # @example Simple hash symbolization
+    #   SymbolizedHash.parse({ 'name' => 'John' })  # => { name: 'John' }
+    # @example Nested hash symbolization
+    #   SymbolizedHash.parse({ 'user' => { 'name' => 'John' } })  # => { user: { name: 'John' } }
+    # @example Mixed types preserved
+    #   SymbolizedHash.parse({ 'count' => 1, 'active' => true })  # => { count: 1, active: true }
+    SymbolizedHash = Hash[
+      # String keys are converted to symbols, existing symbols are preserved
+      (Symbol | String.transform(::Symbol, &:to_sym)),
+      # Hash values are recursively symbolized, other types pass through unchanged
+      Any.defer { SymbolizedHash } | Any
+    ]
+
     module UUID
       V4 = String[/\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i].as_node(:uuid)
     end

data/lib/plumb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Plumb
-  VERSION = '0.0.14'
+  VERSION = '0.0.15'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: plumb
 version: !ruby/object:Gem::Version
-  version: 0.0.14
+  version: 0.0.15
 platform: ruby
 authors:
 - Ismael Celis
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-03 00:00:00.000000000 Z
+date: 2025-10-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal