plumb 0.0.2 → 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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'plumb'
+require 'debug'
+
+# Types and pipelines for defining and parsing ENV configuration
+# Run with `bundle exec ruby examples/env_config.rb`
+#
+# Given an ENV with variables to configure one of three types of network/IO clients,
+# parse, validate and coerce the configuration into the appropriate client object.
+# ENV vars are expected to be prefixed with `FILE_UPLOAD_`, followed by the client type.
+# See example usage at the bottom of this file.
+module Types
+  include Plumb::Types
+
+  # Define a custom policy to extract a string using a regular expression.
+  # Policies are factories for custom type compositions.
+  #
+  # Usage:
+  #   type = Types::String.extract(/^FOO_(\w+)$/).invoke(:[], 1)
+  #   type.parse('FOO_BAR') # => 'BAR'
+  #
+  Plumb.policy :extract, for_type: ::String, helper: true do |type, regex|
+    type >> lambda do |result|
+      match = result.value.match(regex)
+      return result.invalid(errors: "does not match #{regex.source}") if match.nil?
+      return result.invalid(errors: 'no captures') if match.captures.none?
+
+      result.valid(match)
+    end
+  end
+
+  # A dummy S3 client
+  S3Client = ::Data.define(:bucket, :region)
+
+  # A dummy SFTP client
+  SFTPClient = ::Data.define(:host, :username, :password)
+
+  # Map these fields to an S3 client
+  S3Config = Types::Hash[
+    transport: 's3',
+    bucket: String.present,
+    region: String.options(%w[us-west-1 us-west-2 us-east-1])
+  ].invoke(:except, :transport).build(S3Client) { |h| S3Client.new(**h) }
+
+  # Map these fields to an SFTP client
+  SFTPConfig = Types::Hash[
+    transport: 'sftp',
+    host: String.present,
+    username: String.present,
+    password: String.present,
+  ].invoke(:except, :transport).build(SFTPClient) { |h| SFTPClient.new(**h) }
+
+  # Map these fields to a File client
+  FileConfig = Types::Hash[
+    transport: 'file',
+    path: String.present,
+  ].invoke(:[], :path).build(::File)
+
+  # Take a string such as 'FILE_UPLOAD_BUCKET', extract the `BUCKET` bit,
+  # downcase and symbolize it.
+  FileUploadKey = String.extract(/^FILE_UPLOAD_(\w+)$/).invoke(:[], 1).invoke(%i[downcase to_sym])
+
+  # Filter a Hash (or ENV) to keys that match the FILE_UPLOAD_* pattern
+  FileUploadHash = Types::Hash[FileUploadKey, Any].filtered
+
+  # Pipeline syntax to put the program together
+  FileUploadClientFromENV = Any.pipeline do |pl|
+    # 1. Accept any Hash-like object (e.g. ENV)
+    pl.step Types::Interface[:[], :key?, :each, :to_h]
+
+    # 2. Transform it to a Hash
+    pl.step Any.transform(::Hash, &:to_h)
+
+    # 3. Filter keys with FILE_UPLOAD_* prefix
+    pl.step FileUploadHash
+
+    # 4. Parse the configuration for a particular client object
+    pl.step(S3Config | SFTPConfig | FileConfig)
+  end
+
+  # Ex.
+  # client = FileUploadClientFromENV.parse(ENV) # SFTP, S3 or File client
+
+  # The above is the same as:
+  #
+  # FileUploadClientFromENV = Types::Interface[:[], :key?, :each, :to_h] \
+  #                           .transform(::Hash, &:to_h) >> \
+  #                           Types::Hash[FileUploadKey, Any].filtered >> \
+  #                           (S3Config | SFTPConfig | FileConfig)
+end
+
+# Simulated ENV hashes. Just use ::ENV for the real thing.
+ENV_S3 = {
+  'FILE_UPLOAD_TRANSPORT' => 's3',
+  'FILE_UPLOAD_BUCKET' => 'my-bucket',
+  'FILE_UPLOAD_REGION' => 'us-west-2',
+  'SOMETHING_ELSE' => 'ignored'
+}.freeze
+# => S3Client.new(bucket: 'my-bucket', region: 'us-west-2')
+
+ENV_SFTP = {
+  'FILE_UPLOAD_TRANSPORT' => 'sftp',
+  'FILE_UPLOAD_HOST' => 'sftp.example.com',
+  'FILE_UPLOAD_USERNAME' => 'username',
+  'FILE_UPLOAD_PASSWORD' => 'password',
+  'SOMETHING_ELSE' => 'ignored'
+}.freeze
+# => SFTPClient.new(host: 'sftp.example.com', username: 'username', password: 'password')
+
+ENV_FILE = {
+  'FILE_UPLOAD_TRANSPORT' => 'file',
+  'FILE_UPLOAD_PATH' => File.join('examples', 'programmers.csv')
+}.freeze
+
+p Types::FileUploadClientFromENV.parse(ENV_S3) # #<data Types::S3Client bucket="my-bucket", region="us-west-2">
+p Types::FileUploadClientFromENV.parse(ENV_SFTP) # #<data Types::SFTPClient host="sftp.example.com", username="username", password="password">
+p Types::FileUploadClientFromENV.parse(ENV_FILE) # #<File path="examples/programmers.csv">
+
+# Or with invalid or missing configuration
+# p Types::FileUploadClientFromENV.parse({}) # raises error

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

@@ -41,7 +41,7 @@ module Types
   # Ex. [1, 2, 3, 4, 5, 6, 7], [1, 2, 4], ['monday', 'tuesday', 'wednesday', 7]
   # Turn day names into numbers, and sort the array.
   Week = Array[DayNameOrNumber]
-         .rule(size: 1..7)
+         .policy(size: 1..7)
          .check('repeated days') { |days| days.uniq.size == days.size }
          .transform(::Array, &:sort)
 end

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