plumb 0.0.6 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 308e76909c6466b0a6c2cc9443498a267186344b9508b8f485975479e0ff165a
-  data.tar.gz: 8498e5a4619437b8f91b3baae4b2d208c27031a5617dba174d52893cd4e3a54a
+  metadata.gz: 82cbbcfabbe2240d11a1957c7d06f59e314d8013c1459ecdd6339404f0c3208e
+  data.tar.gz: a17828a33c296ba50bffbb629a806f732bc3a9f73d974617e4526bfd74065d42
 SHA512:
-  metadata.gz: d41ebdf232099770d04abc85f81ead1e8dc1d4f55eb1bc9265484401cfd0418e984d7cf97a67a6ef452d67f05c3f92e66e3e3fe64f11622acbb89e5c223c73b1
-  data.tar.gz: 5e2749e954fae81753d63d6d27b95a53f239b5ac6ad776755646d794fe7819b56087f48bd99394aeab2f40c64d45606cc413a1475512f6943279d51a7dd7d2b2
+  metadata.gz: 28ce9c69dcfa1f5d1129745301164400211c1df5707b851a2457f4361b59ed0ad73472851ae2993267f3d74389a6477ded4a60ce3eaed70472c041fad03df7bd
+  data.tar.gz: 45e8f649c646b3236c6e7e5c3c86ed7493b88fc544585e5dc168675c69660b7ca217b5508a834b2dfa1820f97ca87b4edd9b988d17effb82697da28273545e2d

data/README.md

@@ -455,6 +455,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.static { 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.static { 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

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

@@ -160,10 +160,12 @@ module Plumb
 
       @errors = BLANK_HASH
       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

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/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/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: plumb
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.7
 platform: ruby
 authors:
 - Ismael Celis
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-04 00:00:00.000000000 Z
+date: 2024-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal