plumb 0.0.6 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 308e76909c6466b0a6c2cc9443498a267186344b9508b8f485975479e0ff165a
-  data.tar.gz: 8498e5a4619437b8f91b3baae4b2d208c27031a5617dba174d52893cd4e3a54a
+  metadata.gz: 7e5d0ac088968506a61d63da75f4010b050579c873d79604a25dfe0b133d3726
+  data.tar.gz: d559c1a3964544184258043e14d0bf9e3b41ff743a8117eccee09be2c22b084a
 SHA512:
-  metadata.gz: d41ebdf232099770d04abc85f81ead1e8dc1d4f55eb1bc9265484401cfd0418e984d7cf97a67a6ef452d67f05c3f92e66e3e3fe64f11622acbb89e5c223c73b1
-  data.tar.gz: 5e2749e954fae81753d63d6d27b95a53f239b5ac6ad776755646d794fe7819b56087f48bd99394aeab2f40c64d45606cc413a1475512f6943279d51a7dd7d2b2
+  metadata.gz: 1207b06d90baa9833cf39737f2697fb6daf9423d94ca531a99307de561b70415bb6c9ec7fb2394af6c1f8b3f86015996ebfde5db6dc3fa2aadd5284fb1867cb2
+  data.tar.gz: 19131a0a289b8c5082ceb3a9cd716cdabb2d12466bba76ecc5d20c2efd6db3fbb9c04d13c8706996225189de50d81c5d8325fc5527ecc8395c492430fd17393d

data/README.md

@@ -294,6 +294,22 @@ NotEmail.parse('hello') # "hello"
 NotEmail.parse('hello@server.com') # error
 ```
 
+`#not` can also be given a type as argument, which might read better:
+
+```ruby
+Types::Any.not(nil)
+Types::Any.not(Types::Email)
+```
+
+Finally, you can use `Types::Not` for the same effect.
+
+```ruby
+NotNil = Types::Not[nil]
+NotNil.parse(1) # 1
+NotNil.parse('hello') # 'hello'
+NotNil.parse(nil) # error
+```
+
 #### `#options`
 
 Sets allowed options for value.
@@ -455,6 +471,71 @@ All scalar types support this:
 ten = Types::Integer.value(10)
 ```
 
+#### `#static`
+
+A type that always returns a valid, static value, regardless of input.
+
+```ruby
+ten = Types::Integer.static(10)
+ten.parse(10) # => 10
+ten.parse(100) # => 10
+ten.parse('hello') # => 10
+ten.parse() # => 10
+ten.metadata[:type] # => Integer
+```
+
+Useful for data structures where some fields shouldn't change. Example:
+
+```ruby
+CreateUserEvent = Types::Hash[
+  type: Types::String.static('CreateUser'),
+  name: String,
+  age: Integer
+]
+```
+
+Note that the value must be of the same type as the starting step's target type.
+
+```ruby
+Types::Integer.static('nope') # raises ArgumentError
+```
+
+This usage is similar as using `Types::Static['hello']`directly.
+
+This helper is shorthand for the following composition:
+
+```ruby
+Types::Static[value] >> step
+```
+
+This means that validations and coercions in the original step are still applied to the static value.
+
+```ruby
+ten = Types::Integer[100..].static(10)
+ten.parse # => Plumb::ParseError "Must be within 100..."
+```
+
+So, normally you'd only use this attached to primitive types without further processing (but your use case may vary).
+
+#### `#generate`
+
+Passing a proc will evaluate the proc on every invocation. Use this for generated values.
+
+```ruby
+random_number = Types::Numeric.generate { rand }
+random_number.parse # 0.32332
+random_number.parse('foo') # 0.54322 etc
+```
+
+Note that the type of generated value must match the initial step's type, validated at invocation.
+
+```ruby
+random_number = Types::String.generate { rand } # this won't raise an error here
+random_number.parse # raises Plumb::ParseError because `rand` is not a String
+```
+
+You can also pass any `#call() => Object` interface as a generator, instead of a proc.
+
 #### `#metadata`
 
 Add metadata to a type
@@ -1135,6 +1216,30 @@ Payload = Types::Hash[
 ]
 ```
 
+#### Attribute writers
+
+By default `Types::Data` classes are inmutable, but you can define attribute writers to allow for mutation using the `writer: true` option.
+
+```ruby
+class DBConfig < Types::Data
+  attribute :host, Types::String.default('localhost'), writer: true
+end
+
+class Config < Types::Data
+  attribute :host, Types::Forms::URI::HTTP, writer: true
+  attribute :port, Types::Integer.default(80), writer: true
+
+  # Nested structs can have writers too
+  attribute :db, DBConfig.default(DBConfig.new)
+end
+
+config = Config.new
+config.host = 'http://localhost'
+config.db.host = 'db.local'
+config.valid? # true
+config.errors # {}
+```
+
 #### Recursive struct definitions
 
 You can use `#defer`. See [recursive types](#recursive-types).

data/examples/event_registry.rb

@@ -14,9 +14,6 @@ module Types
   # Turn an ISO8601 string into a Time object
   ISOTime = String.build(::Time, :parse).policy(:rescue, ArgumentError)
 
-  # A type that can be a Time object or an ISO8601 string >> Time
-  Time = Any[::Time] | ISOTime
-
   # A UUID string, or generate a new one
   AutoUUID = UUID::V4.default { SecureRandom.uuid }
 end
@@ -60,7 +57,7 @@ class Event < Types::Data
   attribute :id, Types::AutoUUID
   attribute :stream_id, Types::String.present
   attribute :type, Types::String
-  attribute(:created_at, Types::Time.default { ::Time.now })
+  attribute(:created_at, Types::Forms::Time.default { ::Time.now })
   attribute? :causation_id, Types::UUID::V4
   attribute? :correlation_id, Types::UUID::V4
   attribute :payload, Types::Static[nil]

data/lib/plumb/array_class.rb

@@ -45,7 +45,7 @@ module Plumb
     def call(result)
       return result.invalid(errors: 'is not an Array') unless ::Array === result.value
 
-      values, errors = map_array_elements(result.value)
+      values, errors = map_array_elements(result)
       return result.valid(values) unless errors.any?
 
       result.invalid(values, errors:)
@@ -59,14 +59,14 @@ module Plumb
       %(Array[#{element_type}])
     end
 
-    def map_array_elements(list)
+    def map_array_elements(result)
       # Reuse the same result object for each element
       # to decrease object allocation.
       # Steps might return the same result instance, so we map the values directly
       # separate from the errors.
-      element_result = BLANK_RESULT.dup
+      element_result = result.dup
       errors = {}
-      values = list.map.with_index do |e, idx|
+      values = result.value.map.with_index do |e, idx|
         re = element_type.call(element_result.reset(e))
         errors[idx] = re.errors unless re.valid?
         re.value
@@ -78,12 +78,12 @@ module Plumb
     class ConcurrentArrayClass < self
       private
 
-      def map_array_elements(list)
+      def map_array_elements(result)
         errors = {}
 
-        values = list
-                 .map { |e| Concurrent::Future.execute { element_type.resolve(e) } }
-                 .map.with_index do |f, idx|
+        values = result.value
+                       .map { |e| Concurrent::Future.execute { element_type.resolve(e) } }
+                       .map.with_index do |f, idx|
           re = f.value
           errors[idx] = f.reason if f.rejected?
           re.value

data/lib/plumb/attributes.rb

@@ -117,6 +117,7 @@ module Plumb
 
     def initialize(attrs = {})
       assign_attributes(attrs)
+      freeze
     end
 
     def ==(other)
@@ -140,13 +141,18 @@ module Plumb
 
     # @return [Hash]
     def to_h
-      attributes.transform_values do |value|
-        case value
-        when ::Array
-          value.map { |v| v.respond_to?(:to_h) ? v.to_h : v }
-        else
-          value.respond_to?(:to_h) ? value.to_h : value
-        end
+      self.class._schema._schema.keys.each.with_object({}) do |key, memo|
+        key = key.to_sym
+        value = attributes[key]
+        val = case value
+              when ::Array
+                value.map { |v| v.respond_to?(:to_h) ? v.to_h : v }
+              when ::NilClass
+                nil
+              else
+                value.respond_to?(:to_h) ? value.to_h : value
+              end
+        memo[key] = val
       end
     end
 
@@ -158,12 +164,14 @@ module Plumb
     def assign_attributes(attrs = BLANK_HASH)
       raise ArgumentError, 'Must be a Hash of attributes' unless attrs.respond_to?(:to_h)
 
-      @errors = BLANK_HASH
+      @errors = {}
       result = self.class._schema.resolve(attrs.to_h)
-      @attributes = result.value
+      @attributes = prepare_attributes(result.value)
       @errors = result.errors unless result.valid?
     end
 
+    def prepare_attributes(attrs) = attrs
+
     module ClassMethods
       def _schema
         @_schema ||= HashClass.new
@@ -209,7 +217,7 @@ module Plumb
       # attribute(:friends, Types::Array[Person])
       # attribute(:friends, [Person])
       #
-      def attribute(name, type = Types::Any, &block)
+      def attribute(name, type = Types::Any, writer: false, &block)
         key = Key.wrap(name)
         name = key.to_sym
         type = Composable.wrap(type)
@@ -232,13 +240,30 @@ module Plumb
         end
 
         @_schema = _schema + { key => type }
-        __plumb_define_attribute_method__(name)
+        __plumb_define_attribute_reader_method__(name)
+        return name unless writer
+
+        __plumb_define_attribute_writer_method__(name)
       end
 
-      def __plumb_define_attribute_method__(name)
+      def __plumb_define_attribute_reader_method__(name)
         define_method(name) { @attributes[name] }
       end
 
+      def __plumb_define_attribute_writer_method__(name)
+        define_method("#{name}=") do |value|
+          type = self.class._schema.at_key(name)
+          result = type.resolve(value)
+          @attributes[name] = result.value
+          if result.valid?
+            @errors.delete(name)
+          else
+            @errors.merge!(name => result.errors)
+          end
+          result.value
+        end
+      end
+
       def attribute?(name, *args, &block)
         attribute(Key.new(name, optional: true), *args, &block)
       end

data/lib/plumb/composable.rb

@@ -84,6 +84,26 @@ module Plumb
     def node_name = self.class.name.split('::').last.to_sym
   end
 
+  # Override #=== and #== for Composable instances.
+  # but only when included in classes, not extended.
+  module Equality
+    # `#===` equality. So that Plumb steps can be used in case statements and pattern matching.
+    # @param other [Object]
+    # @return [Boolean]
+    def ===(other)
+      case other
+      when Composable
+        other == self
+      else
+        resolve(other).valid?
+      end
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && other.respond_to?(:children) && other.children == children
+    end
+  end
+
   #  Composable mixes in composition methods to classes.
   # such as #>>, #|, #not, and others.
   # Any Composable class can participate in Plumb compositions.
@@ -95,6 +115,7 @@ module Plumb
     # not extending classes with it.
     def self.included(base)
       base.send(:include, Naming)
+      base.send(:include, Equality)
     end
 
     # Wrap an object in a Composable instance.
@@ -304,22 +325,6 @@ module Plumb
       end
     end
 
-    # `#===` equality. So that Plumb steps can be used in case statements and pattern matching.
-    # @param other [Object]
-    # @return [Boolean]
-    def ===(other)
-      case other
-      when Composable
-        other == self
-      else
-        resolve(other).valid?
-      end
-    end
-
-    def ==(other)
-      other.is_a?(self.class) && other.respond_to?(:children) && other.children == children
-    end
-
     # Visitors expect a #node_name and #children interface.
     # @return [Array<Composable>]
     def children = BLANK_ARRAY
@@ -341,6 +346,40 @@ module Plumb
       self >> Build.new(cns, factory_method:, &block)
     end
 
+    # Always return a static value, regardless of the input.
+    # @example
+    #   type = Types::Integer.static(10)
+    #   type.parse(10) # => 10
+    #   type.parse(100) # => 10
+    #   type.parse # => 10
+    #
+    # @param value [Object]
+    # @return [And]
+    def static(value)
+      my_type = Array(metadata[:type]).first
+      unless my_type.nil? || value.instance_of?(my_type)
+        raise ArgumentError,
+              "can't set a static #{value.class} value for a #{my_type} step"
+      end
+
+      StaticClass.new(value) >> self
+    end
+
+    # Return the output of a block or #call interface, regardless of input.
+    # The block will be called to get the value, on every invocation.
+    # @example
+    #  now = Types::Integer.generate { Time.now.to_i }
+    #
+    # @param generator [#call, nil] a callable that will be applied to the value, or nil if block
+    # @param block [Proc] a block that will be applied to the value, or nil if callable
+    # @return [And]
+    def generate(generator = nil, &block)
+      generator ||= block
+      raise ArgumentError, 'expected a generator' unless generator.respond_to?(:call)
+
+      Step.new(->(r) { r.valid(generator.call) }, 'generator') >> self
+    end
+
     # Build a Plumb::Pipeline with this object as the starting step.
     # @example
     #   pipe = Types::Data[name: String].pipeline do |pl|
@@ -351,7 +390,7 @@ module Plumb
     #
     # @return [Pipeline]
     def pipeline(&block)
-      Pipeline.new(self, &block)
+      Pipeline.new(type: self, &block)
     end
 
     def to_s

data/lib/plumb/hash_class.rb

@@ -109,7 +109,7 @@ module Plumb
 
       input = result.value
       errors = {}
-      field_result = BLANK_RESULT.dup
+      field_result = result.dup
       initial = {}
       initial = initial.merge(input) if @inclusive
       output = _schema.each.with_object(initial) do |(key, field), ret|

data/lib/plumb/not.rb

@@ -8,13 +8,19 @@ module Plumb
 
     attr_reader :children, :errors
 
-    def initialize(step, errors: nil)
-      @step = step
-      @errors = errors
+    def initialize(step = nil, errors: nil)
+      @step = Composable.wrap(step)
+      @errors = errors || "must not be #{step.inspect}"
       @children = [step].freeze
       freeze
     end
 
+    # @param step [Object]
+    # @return [Not]
+    def [](step)
+      self.class.new(step)
+    end
+
     private def _inspect
       %(Not(#{@step.inspect}))
     end

data/lib/plumb/pipeline.rb

@@ -37,14 +37,14 @@ module Plumb
 
     attr_reader :children
 
-    def initialize(type = Types::Any, &setup)
+    def initialize(type: Types::Any, freeze_after: true, &setup)
       @type = type
       @children = [type].freeze
       @around_blocks = self.class.around_blocks.dup
       return unless block_given?
 
       configure(&setup)
-      freeze
+      freeze if freeze_after
     end
 
     def call(result)

data/lib/plumb/types.rb

@@ -159,6 +159,7 @@ module Plumb
     Stream = StreamClass.new
     Tuple = TupleClass.new
     Hash = HashClass.new
+    Not = Plumb::Not.new
     Interface = InterfaceClass.new
     Email = String[URI::MailTo::EMAIL_REGEXP].as_node(:email)
     Date = Any[::Date]

data/lib/plumb/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: plumb
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.8
 platform: ruby
 authors:
 - Ismael Celis
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-04 00:00:00.000000000 Z
+date: 2024-10-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -115,7 +115,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
+rubygems_version: 3.5.21
 signing_key:
 specification_version: 4
 summary: Data validation and transformation library.