plumb 0.0.3 → 0.0.4

data/examples/concurrent_downloads.rb

@@ -15,8 +15,8 @@ module Types
   # Turn a string into an URI
   URL = String[/^https?:/].build(::URI, :parse)
 
-  # a Struct to holw image data
-  Image = Data.define(:url, :io)
+  # a Struct to hold image data
+  Image = ::Data.define(:url, :io)
 
   # A (naive) step to download files from the internet
   # and return an Image struct.
@@ -38,7 +38,7 @@ module Types
     # Wrap the #reader and #wruter methods into Plumb steps
     # A step only needs #call(Result) => Result to work in a pipeline,
     # but wrapping it in Plumb::Step provides the #>> and #| methods for composability,
-    # as well as all the other helper methods provided by the Steppable module.
+    # as well as all the other helper methods provided by the Composable module.
     def read = Plumb::Step.new(method(:reader))
     def write = Plumb::Step.new(method(:writer))
 

data/examples/env_config.rb

@@ -32,10 +32,10 @@ module Types
   end
 
   # A dummy S3 client
-  S3Client = Data.define(:bucket, :region)
+  S3Client = ::Data.define(:bucket, :region)
 
   # A dummy SFTP client
-  SFTPClient = Data.define(:host, :username, :password)
+  SFTPClient = ::Data.define(:host, :username, :password)
 
   # Map these fields to an S3 client
   S3Config = Types::Hash[

data/examples/event_registry.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require 'plumb'
+require 'time'
+require 'uri'
+require 'securerandom'
+require 'debug'
+
+# Bring Plumb into our own namespace
+# and define some basic types
+module Types
+  include Plumb::Types
+
+  # Turn an ISO8601 sring into a Time object
+  ISOTime = String.build(::Time, :parse)
+
+  # A type that can be a Time object or an ISO8601 string >> Time
+  Time = Any[::Time] | ISOTime
+
+  # A UUID string
+  UUID = String[/\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i]
+
+  # A UUID string, or generate a new one
+  AutoUUID = UUID.default { SecureRandom.uuid }
+
+  Email = String[URI::MailTo::EMAIL_REGEXP]
+end
+
+# A superclass and registry to define event types
+# for example for an event-driven or event-sourced system.
+# All events have an "envelope" set of attributes,
+# including unique ID, stream_id, type, timestamp, causation ID,
+# event subclasses have a type string (ex. 'users.name.updated') and an optional payload
+# This class provides a `.define` method to create new event types with a type and optional payload struct,
+# a `.from` method to instantiate the correct subclass from a hash, ex. when deserializing from JSON or a web request.
+# and a `#follow` method to produce new events based on a previous event's envelope, where the #causation_id and #correlation_id
+# are set to the parent event
+# @example
+#
+#  # Define event struct with type and payload
+#  UserCreated = Event.define('users.created') do
+#    attribute :name, Types::String
+#    attribute :email, Types::Email
+#  end
+#
+#  # Instantiate a full event with .new
+#  user_created = UserCreated.new(stream_id: 'user-1', payload: { name: 'Joe', email: '...' })
+#
+#  # Use the `.from(Hash) => Event` factory to lookup event class by `type` and produce the right instance
+#  user_created = Event.from(type: 'users.created', stream_id: 'user-1', payload: { name: 'Joe', email: '...' })
+#
+#  # Use #follow(payload Hash) => Event to produce events following a command or parent event
+#  create_user = CreateUser.new(...)
+#  user_created = create_user.follow(UserCreated, name: 'Joe', email: '...')
+#  user_created.causation_id == create_user.id
+#  user_created.correlation_id == create_user.correlation_id
+#  user_created.stream_id == create_user.stream_id
+#
+# ## JSON Schemas
+# Plumb data structs support `.to_json_schema`, to you can document all events in the registry with something like
+#
+#   Event.registry.values.map(&:to_json_schema)
+#
+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? :causation_id, Types::UUID
+  attribute? :correlation_id, Types::UUID
+  attribute :payload, Types::Static[nil]
+
+  def self.registry
+    @registry ||= {}
+  end
+
+  def self.define(type_str, &payload_block)
+    type_str.freeze unless type_str.frozen?
+    registry[type_str] = Class.new(self) do
+      attribute :type, Types::Static[type_str]
+      attribute :payload, &payload_block if block_given?
+    end
+  end
+
+  def self.from(attrs)
+    klass = registry[attrs[:type]]
+    raise ArgumentError, "Unknown event type: #{attrs[:type]}" unless klass
+
+    klass.new(attrs)
+  end
+
+  def follow(event_class, payload_attrs = nil)
+    attrs = { stream_id:, causation_id: id, correlation_id: }
+    attrs[:payload] = payload_attrs if payload_attrs
+    event_class.new(attrs)
+  end
+end
+
+# Example command and events for a simple event-sourced system
+#
+# ## Commands
+# CreateUser = Event.define('users.create') do
+#   attribute :name, Types::String.present
+#   attribute :email, Types::Email
+# end
+#
+# UpdateUserName = Event.define('users.update_name') do
+#   attribute :name, Types::String.present
+# end
+#
+# ## Events
+# UserCreated = Event.define('users.created') do
+#   attribute :name, Types::String
+#   attribute :email, Types::Email
+# end
+#
+# UserNameUpdated = Event.define('users.name_updated') do
+#   attribute :name, Types::String
+# end
+# debugger

data/lib/plumb/and.rb

@@ -1,16 +1,17 @@
 # frozen_string_literal: true
 
-require 'plumb/steppable'
+require 'plumb/composable'
 
 module Plumb
   class And
-    include Steppable
+    include Composable
 
-    attr_reader :left, :right
+    attr_reader :children
 
     def initialize(left, right)
       @left = left
       @right = right
+      @children = [left, right].freeze
       freeze
     end
 

data/lib/plumb/any_class.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
-require 'plumb/steppable'
+require 'plumb/composable'
 
 module Plumb
   class AnyClass
-    include Steppable
+    include Composable
 
-    def |(other) = Steppable.wrap(other)
-    def >>(other) = Steppable.wrap(other)
+    def |(other) = Composable.wrap(other)
+    def >>(other) = Composable.wrap(other)
 
     # Any.default(value) must trigger default when value is Undefined
     def default(...)

data/lib/plumb/array_class.rb

@@ -1,18 +1,19 @@
 # frozen_string_literal: true
 
 require 'concurrent'
-require 'plumb/steppable'
+require 'plumb/composable'
 require 'plumb/result'
 require 'plumb/stream_class'
 
 module Plumb
   class ArrayClass
-    include Steppable
+    include Composable
 
-    attr_reader :element_type
+    attr_reader :children
 
     def initialize(element_type: Types::Any)
-      @element_type = Steppable.wrap(element_type)
+      @element_type = Composable.wrap(element_type)
+      @children = [@element_type].freeze
 
       freeze
     end
@@ -47,11 +48,13 @@ module Plumb
       values, errors = map_array_elements(result.value)
       return result.valid(values) unless errors.any?
 
-      result.invalid(errors:)
+      result.invalid(values, errors:)
     end
 
     private
 
+    attr_reader :element_type
+
     def _inspect
       %(Array[#{element_type}])
     end

data/lib/plumb/attributes.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+module Plumb
+  module Attributes
+    # A module that provides a simple way to define a struct-like class with
+    # attributes that are type-checked on initialization.
+    #
+    # @example
+    #   class Person
+    #     include Plumb::Attributes
+    #
+    #     attribute :name, Types::String
+    #     attribute :age, Types::Integer[18..]
+    #   end
+    #
+    #   person = Person.new(name: 'Jane', age: 20)
+    #   person.valid? # => true
+    #   person.errors # => {}
+    #   person.name # => 'Jane'
+    #
+    # It supports nested attributes:
+    #
+    # @example
+    #   class Person
+    #     include Plumb::Attributes
+    #
+    #     attribute :friend do
+    #       attribute :name, String
+    #     end
+    #   end
+    #
+    #   person = Person.new(friend: { name: 'John' })
+    #
+    # Or arrays of nested attributes:
+    #
+    # @example
+    #   class Person
+    #     include Plumb::Attributes
+    #
+    #     attribute :friends, Types::Array do
+    #       atrribute :name, String
+    #     end
+    #   end
+    #
+    #   person = Person.new(friends: [{ name: 'John' }])
+    #
+    # Or use struct classes defined separately:
+    #
+    # @example
+    #   class Company
+    #     include Plumb::Attributes
+    #     attribute :name, String
+    #   end
+    #
+    #   class Person
+    #     include Plumb::Attributes
+    #
+    #     # Single nested struct
+    #     attribute :company, Company
+    #
+    #     # Array of nested structs
+    #     attribute :companies, Types::Array[Company]
+    #   end
+    #
+    # Arrays and other types support composition and helpers. Ex. `#default`.
+    #
+    #   attribute :companies, Types::Array[Company].default([].freeze)
+    #
+    # Passing a named struct class AND a block will subclass the struct and extend it with new attributes:
+    #
+    #   attribute :company, Company do
+    #     attribute :address, String
+    #   end
+    #
+    # The same works with arrays:
+    #
+    #   attribute :companies, Types::Array[Company] do
+    #     attribute :address, String
+    #   end
+    #
+    # Note that this does NOT work with union'd or piped structs.
+    #
+    #   attribute :company, Company | Person do
+    #
+    # ## Optional Attributes
+    # Using `attribute?` allows for optional attributes. If the attribute is not present, it will be set to `Undefined`.
+    #
+    #   attribute? :company, Company
+    #
+    # ## Struct Inheritance
+    # Structs can inherit from other structs. This is useful for defining a base struct with common attributes.
+    #
+    #   class BasePerson
+    #     include Plumb::Attributes
+    #
+    #     attribute :name, String
+    #   end
+    #
+    #   class Person < BasePerson
+    #     attribute :age, Integer
+    #   end
+    #
+    # ## [] Syntax
+    #
+    # The `[]` syntax can be used to define a struct in a single line.
+    # Like Plumb::Types::Hash, suffixing a key with `?` makes it optional.
+    #
+    #   Person = Data[name: String, age?: Integer]
+    #   person = Person.new(name: 'Jane')
+    #
+    def self.included(base)
+      base.send(:extend, ClassMethods)
+    end
+
+    attr_reader :errors, :attributes
+
+    def initialize(attrs = {})
+      assign_attributes(attrs)
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && other.attributes == attributes
+    end
+
+    # @return [Boolean]
+    def valid? = !errors || errors.none?
+
+    # @param attrs [Hash]
+    # @return [Plumb::Attributes]
+    def with(attrs = BLANK_HASH)
+      self.class.new(attributes.merge(attrs))
+    end
+
+    def inspect
+      %(#<#{self.class}:#{object_id} [#{valid? ? 'valid' : 'invalid'}] #{attributes.map do |k, v|
+                                                                           [k, v.inspect].join(':')
+                                                                         end.join(' ')}>)
+    end
+
+    # @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
+      end
+    end
+
+    def deconstruct(...) = to_h.values.deconstruct(...)
+    def deconstruct_keys(...) = to_h.deconstruct_keys(...)
+
+    private
+
+    def assign_attributes(attrs = BLANK_HASH)
+      raise ArgumentError, 'Must be a Hash of attributes' unless attrs.is_a?(::Hash)
+
+      @errors = BLANK_HASH
+      result = self.class._schema.resolve(attrs)
+      @attributes = result.value
+      @errors = result.errors unless result.valid?
+    end
+
+    module ClassMethods
+      def _schema
+        @_schema ||= HashClass.new
+      end
+
+      def inherited(subclass)
+        _schema._schema.each do |key, type|
+          subclass.attribute(key, type)
+        end
+        super
+      end
+
+      # The Plumb::Step interface
+      # @param result [Plumb::Result::Valid]
+      # @return [Plumb::Result::Valid, Plumb::Result::Invalid]
+      def call(result)
+        return result if result.value.is_a?(self)
+        return result.invalid(errors: ['Must be a Hash of attributes']) unless result.value.is_a?(Hash)
+
+        instance = new(result.value)
+        instance.valid? ? result.valid(instance) : result.invalid(instance, errors: instance.errors)
+      end
+
+      # Person = Data[:name => String, :age => Integer, title?: String]
+      def [](type_specs)
+        klass = Class.new(self)
+        type_specs.each do |key, type|
+          klass.attribute(key, type)
+        end
+        klass
+      end
+
+      # node name for visitors
+      def node_name = :data
+
+      # attribute(:friend) { attribute(:name, String) }
+      # attribute(:friend, MyStruct) { attribute(:name, String) }
+      # attribute(:name, String)
+      # attribute(:friends, Types::Array) { attribute(:name, String) }
+      # attribute(:friends, Types::Array) # same as Types::Array[Types::Any]
+      # attribute(:friends, Types::Array[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 = Types::Data if type == Types::Any
+          type = Plumb.decorate(type) do |node|
+            if node.is_a?(Plumb::ArrayClass)
+              child = node.children.first
+              child = Types::Data if child == Types::Any
+              Types::Array[build_nested(name, child, &block)]
+            elsif node.is_a?(Plumb::Step)
+              build_nested(name, node, &block)
+            elsif node.is_a?(Class) && node <= Plumb::Attributes
+              build_nested(name, node, &block)
+            else
+              node
+            end
+          end
+        end
+
+        @_schema = _schema + { key => type }
+        define_method(name) { @attributes[name] }
+      end
+
+      def attribute?(name, *args, &block)
+        attribute(Key.new(name, optional: true), *args, &block)
+      end
+
+      def build_nested(name, node, &block)
+        if node.is_a?(Class) && node <= Plumb::Attributes
+          sub = Class.new(node)
+          sub.instance_exec(&block)
+          __set_nested_class__(name, sub)
+          return Composable.wrap(sub)
+        end
+
+        return node unless node.is_a?(Plumb::Step)
+
+        child = node.children.first
+        return node unless child <= Plumb::Attributes
+
+        sub = Class.new(child)
+        sub.instance_exec(&block)
+        __set_nested_class__(name, sub)
+        Composable.wrap(sub)
+      end
+
+      def __set_nested_class__(name, klass)
+        name = name.to_s.split('_').map(&:capitalize).join.sub(/s$/, '')
+        const_set(name, klass) unless const_defined?(name)
+      end
+    end
+  end
+end

data/lib/plumb/build.rb

@@ -1,16 +1,17 @@
 # frozen_string_literal: true
 
-require 'plumb/steppable'
+require 'plumb/composable'
 
 module Plumb
   class Build
-    include Steppable
+    include Composable
 
-    attr_reader :type
+    attr_reader :children
 
     def initialize(type, factory_method: :new, &block)
       @type = type
       @block = block || ->(value) { type.send(factory_method, value) }
+      @children = [type].freeze
       freeze
     end
 

data/lib/plumb/{steppable.rb → composable.rb}

@@ -23,10 +23,6 @@ module Plumb
   NOOP = ->(result) { result }
 
   module Callable
-    def metadata
-      MetadataVisitor.call(self)
-    end
-
     def resolve(value = Undefined)
       call(Result.wrap(value))
     end
@@ -43,9 +39,15 @@ module Plumb
     end
   end
 
-  module Steppable
-    include Callable
+  # This module gets included by Composable,
+  # but only when Composable is `included` in classes, not `extended`.
+  # The rule of this module is to assign a name to constants that point to Composable instances.
+  module Naming
+    attr_reader :name
 
+    # When including this module,
+    # define a #node_name method on the Composable instance
+    # #node_name is used by Visitors to determine the type of node.
     def self.included(base)
       nname = base.name.split('::').last
       nname.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
@@ -55,20 +57,6 @@ module Plumb
       base.define_method(:node_name) { nname }
     end
 
-    def self.wrap(callable)
-      if callable.is_a?(Steppable)
-        callable
-      elsif callable.is_a?(::Hash)
-        HashClass.new(schema: callable)
-      elsif callable.respond_to?(:call)
-        Step.new(callable)
-      else
-        MatchClass.new(callable)
-      end
-    end
-
-    attr_reader :name
-
     class Name
       def initialize(name)
         @name = name
@@ -94,17 +82,42 @@ module Plumb
     def inspect = name.to_s
 
     def node_name = self.class.name.split('::').last.to_sym
+  end
+
+  #  Composable mixes in composition methods to classes.
+  # such as #>>, #|, #not, and others.
+  # Any Composable class can participate in Plumb compositions.
+  module Composable
+    include Callable
+
+    # This only runs when including Composable,
+    # not extending classes with it.
+    def self.included(base)
+      base.send(:include, Naming)
+    end
+
+    def self.wrap(callable)
+      if callable.is_a?(Composable)
+        callable
+      elsif callable.is_a?(::Hash)
+        HashClass.new(schema: callable)
+      elsif callable.respond_to?(:call)
+        Step.new(callable)
+      else
+        MatchClass.new(callable)
+      end
+    end
 
     def defer(definition = nil, &block)
       Deferred.new(definition || block)
     end
 
     def >>(other)
-      And.new(self, Steppable.wrap(other))
+      And.new(self, Composable.wrap(other))
     end
 
     def |(other)
-      Or.new(self, Steppable.wrap(other))
+      Or.new(self, Composable.wrap(other))
     end
 
     def transform(target_type, callable = nil, &block)
@@ -115,8 +128,12 @@ module Plumb
       self >> MatchClass.new(block, error: errors, label: errors)
     end
 
-    def meta(data = {})
-      self >> Metadata.new(data)
+    def metadata(data = Undefined)
+      if data == Undefined
+        MetadataVisitor.call(self)
+      else
+        self >> Metadata.new(data)
+      end
     end
 
     def not(other = self)
@@ -138,7 +155,7 @@ module Plumb
     def [](val) = match(val)
 
     class Node
-      include Steppable
+      include Composable
 
       attr_reader :node_name, :type, :attributes
 
@@ -168,11 +185,15 @@ module Plumb
         types = Array(metadata[:type]).uniq
 
         bargs = [self]
-        bargs << rest.first if rest.any?
+        arg = Undefined
+        if rest.any?
+          bargs << rest.first
+          arg = rest.first
+        end
         block = Plumb.policies.get(types, name)
         pol = block.call(*bargs, &blk)
 
-        Policy.new(name, rest.first, pol)
+        Policy.new(name, arg, pol)
       in [::Hash => opts] # #policy(p1: value, p2: value)
         opts.reduce(self) { |step, (name, value)| step.policy(name, value) }
       else
@@ -182,13 +203,19 @@ module Plumb
 
     def ===(other)
       case other
-      when Steppable
+      when Composable
         other == self
       else
         resolve(other).valid?
       end
     end
 
+    def ==(other)
+      other.is_a?(self.class) && other.children == children
+    end
+
+    def children = BLANK_ARRAY
+
     def build(cns, factory_method = :new, &block)
       self >> Build.new(cns, factory_method:, &block)
     end
@@ -201,6 +228,12 @@ module Plumb
       inspect
     end
 
+    # @option root [Boolean] whether to include JSON Schema $schema property
+    # @return [Hash]
+    def to_json_schema(root: false)
+      JSONSchemaVisitor.call(self, root:)
+    end
+
     # Build a step that will invoke one or more methods on the value.
     # Ex 1: Types::String.invoke(:downcase)
     # Ex 2: Types::Array.invoke(:[], 1)