plumb 0.0.5 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 896f2ec4a63cde86dd22aaec579696e19c980b09c09e4a4d9d4690f9505f742d
-  data.tar.gz: 3296480dd0026e8050b624e3e1d65a020fde376a87c4ba269c6481b57c40d19e
+  metadata.gz: 82cbbcfabbe2240d11a1957c7d06f59e314d8013c1459ecdd6339404f0c3208e
+  data.tar.gz: a17828a33c296ba50bffbb629a806f732bc3a9f73d974617e4526bfd74065d42
 SHA512:
-  metadata.gz: 76ecebbe1dc408630107170a213d0145af08bc8d9cec3ef28d66f8aa1eb3fee09352ae89c00aed1eb11b3a52709100f65e6f0a2a43b4a38ed777709f096f9198
-  data.tar.gz: 0cdbf9c24900fdbcd8393dc4f1d260063b303cc44cf84caa86bdb4d34a6edf77e1f75e431481121b9004c7fbac695f3021b4a7be965c34c1d4b96146f17c2c4c
+  metadata.gz: 28ce9c69dcfa1f5d1129745301164400211c1df5707b851a2457f4361b59ed0ad73472851ae2993267f3d74389a6477ded4a60ce3eaed70472c041fad03df7bd
+  data.tar.gz: 45e8f649c646b3236c6e7e5c3c86ed7493b88fc544585e5dc168675c69660b7ca217b5508a834b2dfa1820f97ca87b4edd9b988d17effb82697da28273545e2d

data/README.md

@@ -135,7 +135,7 @@ joe = User.parse({ name: 'Joe', email: 'joe@email.com', age: 20}) # returns vali
 Users.parse([joe]) # returns valid array of user hashes
 ```
 
-More about [Types::Array](#typeshash) and [Types::Array](#typesarray). There's also [tuples](#typestuple), [hash maps](#hash-maps) and [data structs](#typesdata), and it's possible to create your own composite types.
+More about [Types::Hash](#typeshash) and [Types::Array](#typesarray). There's also [tuples](#typestuple), [hash maps](#hash-maps), [data structs](#typesdata) and [streams](#typesstream), and it's possible to create your own composite types.
 
 ### Type composition
 
@@ -235,6 +235,10 @@ You can see more use cases in [the examples directory](https://github.com/ismasa
 * `Types::UUID::V4`
 * `Types::Email`
 * `Types::Date`
+* `Types::Time`
+* `Types::URI::Generic`
+* `Types::URI::HTTP`
+* `Types::URI::File`
 * `Types::Lax::Integer`
 * `Types::Lax::String`
 * `Types::Lax::Symbol`
@@ -243,6 +247,10 @@ You can see more use cases in [the examples directory](https://github.com/ismasa
 * `Types::Forms::True`
 * `Types::Forms::False`
 * `Types::Forms::Date`
+* `Types::Forms::Time`
+* `Types::Forms::URI::Generic`
+* `Types::Forms::URI::HTTP`
+* `Types::Forms::URI::File`
 
 TODO: datetime, others.
 
@@ -447,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
@@ -824,13 +897,15 @@ Images = Types::Array[ImageDownload].concurrent
 Images.parse(['https://images.com/1.png', 'https://images.com/2.png'])
 ```
 
+See the [concurrent downloads example](https://github.com/ismasan/plumb/blob/main/examples/concurrent_downloads.rb).
+
 TODO: pluggable concurrency engines (Async?)
 
 #### `#stream`
 
 Turn an Array definition into an enumerator that yields each element wrapped in `Result::Valid` or `Result::Invalid`.
 
-See `Types::Stream` below for more.
+See [`Types::Stream`](#typesstream) below for more.
 
 #### `#filtered`
 
@@ -899,6 +974,8 @@ stream.each.with_index(1) do |result, line|
 end
 ```
 
+See a more complete the [CSV Stream example](https://github.com/ismasan/plumb/blob/main/examples/csv_stream.rb)
+
 #### `Types::Stream#filtered`
 
 Use `#filtered` to turn a `Types::Stream` into a stream that only yields valid elements.
@@ -1053,7 +1130,25 @@ Note that this does NOT work with union'd or piped structs.
 attribute :company, Company | Person do
 ```
 
+#### Shorthand array syntax
+
+```ruby
+attribute :things, [] # Same as attribute :things, Types::Array
+attribute :numbers, [Integer] # Same as attribute :numbers, Types::Array[Integer]
+attribute :people, [Person] # same as attribute :people, Types::Array[Person]
+attribute :friends, [Person] do # same as attribute :friends, Types::Array[Person] do...
+  attribute :phone_number, Integer
+end
+```
+
+Note that, if you want to match an attribute value against a literal array, you need to use `#value`
+
+```ruby
+attribute :one_two_three, Types::Array.value[[1, 2, 3]])
+```
+
 #### Optional Attributes
+
 Using `attribute?` allows for optional attributes. If the attribute is not present, these attribute values will be `nil`
 
 ```ruby
@@ -1149,7 +1244,7 @@ CreateUser = User.pipeline do |pl|
   end
 end
 
-# User normally as any other Plumb step
+# Use normally as any other Plumb step
 result = CreateUser.resolve(name: 'Joe', age: 40)
 # result.valid?
 # result.errors
@@ -1189,7 +1284,7 @@ end
 Note that order matters: an _around_ step will only wrap steps registered _after it_.
 
 ```ruby
-# This step will not be wrapper by StepLogger
+# This step will not be wrapped by StepLogger
 pl.step Step1
 
 pl.around StepLogger
@@ -1227,7 +1322,7 @@ end
 ```ruby
 class LoggedPipeline < Plumb::Pipeline
   # class-level midleware will be inherited by sub-classes
-  around StepLogged
+  around StepLogger
 end
 
 # Subclass inherits class-level middleware stack,

data/bench/plumb_hash.rb

@@ -12,22 +12,12 @@ module PlumbHash
   BLANK_STRING = ''
   MONEY_EXP = /(\W{1}|\w{3})?[\d+,.]/
 
-  PARSE_DATE = proc do |result|
-    date = ::Date.parse(result.value)
-    result.valid(date)
-  rescue ::Date::Error
-    result.invalid(errors: 'invalid date')
-  end
-
   PARSE_MONEY = proc do |result|
     value = Monetize.parse!(result.value.to_s.gsub(',', ''))
     result.valid(value)
   end
 
-  Date = Any[::Date] \
-    | (String[MONEY_EXP] >> PARSE_DATE)
-
-  BlankStringOrDate = Forms::Nil | Date
+  BlankStringOrDate = Forms::Nil | Forms::Date
 
   Money = Any[::Money] \
     | (String.present >> PARSE_MONEY) \

data/examples/command_objects.rb

@@ -26,9 +26,6 @@ module Types
   # Turn integers into Money objects (requires the money gem)
   Amount = Integer.build(Money)
 
-  # A naive email check
-  Email = String[/\w+@\w+\.\w+/]
-
   # A valid customer type
   Customer = Hash[
     name: String.present,

data/examples/concurrent_downloads.rb

@@ -12,9 +12,6 @@ require 'digest/md5'
 module Types
   include Plumb::Types
 
-  # Turn a string into an URI
-  URL = String[/^https?:/].build(::URI, :parse)
-
   # a Struct to hold image data
   Image = ::Data.define(:url, :io)
 
@@ -24,7 +21,7 @@ module Types
   # required by all Plumb steps.
   # URI => Image
   Download = Plumb::Step.new do |result|
-    io = URI.open(result.value)
+    io = ::URI.open(result.value)
     result.valid(Image.new(result.value.to_s, io))
   end
 
@@ -81,7 +78,7 @@ cache = Types::Cache.new('./examples/data/downloads')
 # 1). Take a valid URL string.
 # 2). Attempt reading the file from the cache. Return that if it exists.
 # 3). Otherwise, download the file from the internet and write it to the cache.
-IdempotentDownload = Types::URL >> (cache.read | (Types::Download >> cache.write))
+IdempotentDownload = Types::Forms::URI::HTTP >> (cache.read | (Types::Download >> cache.write))
 
 # An array of downloadable images,
 # marked as concurrent so that all IO operations are run in threads.

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/examples/weekdays.rb

@@ -4,7 +4,7 @@ require 'bundler'
 Bundler.setup(:examples)
 require 'plumb'
 
-#   bundle exec examples/weekdays.rb
+#   bundle exec ruby examples/weekdays.rb
 #
 # Data types to represent and parse an array of days of the week.
 # Input data can be an array of day names or numbers, ex.

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
@@ -205,12 +207,15 @@ module Plumb
       # attribute(:name, String)
       # attribute(:friends, Types::Array) { attribute(:name, String) }
       # attribute(:friends, Types::Array) # same as Types::Array[Types::Any]
+      # attribute(:friends, []) # same as Types::Array[Types::Any]
       # attribute(:friends, Types::Array[Person])
+      # attribute(:friends, [Person])
       #
       def attribute(name, type = Types::Any, &block)
         key = Key.wrap(name)
         name = key.to_sym
         type = Composable.wrap(type)
+
         if block_given? # :foo, Array[Data] or :foo, Struct
           type = __plumb_struct_class__ if type == Types::Any
           type = Plumb.decorate(type) do |node|

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,11 +115,13 @@ 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.
     # Anything that includes Composable is a noop.
     # A Hash is assumed to be a HashClass schema.
+    # An Array with zero or 1 element is assumed to be an ArrayClass.
     # Any `#call(Result) => Result` interface is wrapped in a Step.
     # Anything else is assumed to be something you want to match against via `#===`.
     #
@@ -115,6 +137,16 @@ module Plumb
         callable
       elsif callable.is_a?(::Hash)
         HashClass.new(schema: callable)
+      elsif callable.is_a?(::Array)
+        element_type = case callable.size
+                       when 0
+                         Types::Any
+                       when 1
+                         callable.first
+                       else
+                         raise ArgumentError, '[element_type] syntax allows a single element type'
+                       end
+        Types::Array[element_type]
       elsif callable.respond_to?(:call)
         Step.new(callable)
       else
@@ -293,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
@@ -330,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|
@@ -340,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|
@@ -139,17 +139,8 @@ module Plumb
     end
 
     def wrap_keys_and_values(hash)
-      case hash
-      when ::Array
-        hash.map { |e| wrap_keys_and_values(e) }
-      when ::Hash
-        hash.each.with_object({}) do |(k, v), ret|
-          ret[Key.wrap(k)] = wrap_keys_and_values(v)
-        end
-      when Callable
-        hash
-      else #  leaf values
-        Composable.wrap(hash)
+      hash.each.with_object({}) do |(k, v), ret|
+        ret[Key.wrap(k)] = Composable.wrap(v)
       end
     end
 

data/lib/plumb/json_schema_visitor.rb

@@ -255,6 +255,18 @@ module Plumb
       props.merge(TYPE => 'string', FORMAT => 'date')
     end
 
+    on(::URI::Generic) do |_node, props|
+      props.merge(TYPE => 'string', FORMAT => 'uri')
+    end
+
+    on(::URI::HTTP) do |_node, props|
+      props.merge(TYPE => 'string', FORMAT => 'uri')
+    end
+
+    on(::URI::File) do |_node, props|
+      props.merge(TYPE => 'string', FORMAT => 'uri')
+    end
+
     on(::Hash) do |_node, props|
       props.merge(TYPE => 'object')
     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

@@ -3,6 +3,7 @@
 require 'bigdecimal'
 require 'uri'
 require 'date'
+require 'time'
 
 module Plumb
   # Define core policies
@@ -161,11 +162,18 @@ module Plumb
     Interface = InterfaceClass.new
     Email = String[URI::MailTo::EMAIL_REGEXP].as_node(:email)
     Date = Any[::Date]
+    Time = Any[::Time]
 
     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
 
+    module URI
+      Generic = Any[::URI::Generic]
+      HTTP = Any[::URI::HTTP]
+      File = Any[::URI::File]
+    end
+
     class Data
       extend Composable
       include Plumb::Attributes
@@ -214,6 +222,16 @@ module Plumb
       # Accept a Date, or a string that can be parsed into a Date
       # via Date.parse
       Date = Date | (String >> Any.build(::Date, :parse).policy(:rescue, ::Date::Error))
+      Time = Time | (String >> Any.build(::Time, :parse).policy(:rescue, ::ArgumentError))
+
+      # Turn strings into different URI types
+      module URI
+        # URI.parse is very permisive - a blank string is valid.
+        # We want to ensure that a generic URI at least starts with a scheme as per RFC 3986
+        Generic = Types::URI::Generic | (String[/^([a-z][a-z0-9+\-.]*)/].build(::URI, :parse))
+        HTTP = Generic[::URI::HTTP]
+        File = Generic[::URI::File]
+      end
     end
   end
 end

data/lib/plumb/version.rb

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

metadata

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