plumb 0.0.1 → 0.0.3

data/examples/command_objects.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require 'bundler'
+Bundler.setup(:examples)
+require 'plumb'
+require 'json'
+require 'fileutils'
+require 'money'
+
+Money.default_currency = Money::Currency.new('GBP')
+Money.locale_backend = nil
+Money.rounding_mode = BigDecimal::ROUND_HALF_EVEN
+
+# Different approaches to the Command Object pattern using composable Plumb types.
+module Types
+  include Plumb::Types
+
+  # Note that within this `Types` module, when we say String, Integer etc, we mean Types::String, Types::Integer etc.
+  # Use ::String to refer to Ruby's String class.
+  #
+  ###############################################################
+  # Define core types in the domain
+  # The task is to process, validate and store mortgage applications.
+  ###############################################################
+
+  # 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,
+    age?: Integer[18..],
+    email: Email
+  ]
+
+  # A step to validate a Mortgage application payload
+  # including valid customer, mortgage type and minimum property value.
+  MortgagePayload = Hash[
+    customer: Customer,
+    type: String.options(%w[first-time switcher remortgage]).default('first-time'),
+    property_value: Integer[100_000..] >> Amount,
+    mortgage_amount: Integer[50_000..] >> Amount,
+    term: Integer[5..30],
+  ]
+
+  # A domain validation step: the mortgage amount must be less than the property value.
+  # This is just a Proc that implements the `#call(Result::Valid) => Result::Valid | Result::Invalid` interface.
+  # # Note that this can be anything that supports that interface, like a lambda, a method, a class etc.
+  ValidateMortgageAmount = proc do |result|
+    if result.value[:mortgage_amount] > result.value[:property_value]
+      result.invalid(errors: { mortgage_amount: 'Cannot exceed property value' })
+    else
+      result
+    end
+  end
+
+  # A step to create a mortgage application
+  # This could be backed by a database (ex. ActiveRecord), a service (ex. HTTP API), etc.
+  # For this example I just save JSON files to disk.
+  class MortgageApplicationsStore
+    def self.call(result) = new.call(result)
+
+    def initialize(dir = './examples/data/applications')
+      @dir = dir
+      FileUtils.mkdir_p(dir)
+    end
+
+    # The Plumb::Step interface to make these objects composable.
+    # @param result [Plumb::Result::Valid]
+    # @return [Plumb::Result::Valid, Plumb::Result::Invalid]
+    def call(result)
+      if save(result.value)
+        result
+      else
+        result.invalid(errors: 'Could not save application')
+      end
+    end
+
+    def save(payload)
+      file_name = File.join(@dir, "#{Time.now.to_i}.json")
+      File.write(file_name, JSON.pretty_generate(payload))
+    end
+  end
+
+  # Finally, a step to send a notificiation to the customer.
+  # This should only run if the previous steps were successful.
+  NotifyCustomer = proc do |result|
+    # Send an email here.
+    puts "Sending notification to #{result.value[:customer][:email]}"
+    result
+  end
+
+  ###############################################################
+  # Option 1: define standalone steps and then pipe them together
+  ###############################################################
+  CreateMortgageApplication1 = MortgagePayload \
+    >> ValidateMortgageAmount \
+    >> MortgageApplicationsStore \
+    >> NotifyCustomer
+
+  ###############################################################
+  # Option 2: compose steps into a Plumb::Pipeline
+  # This is just a wrapper around step1 >> step2 >> step3 ...
+  # But the procedural style can make sequential steps easier to read and manage.
+  # Also to add/remove debugging and tracing steps.
+  ###############################################################
+  CreateMortgageApplication2 = Any.pipeline do |pl|
+    # The input payload
+    pl.step MortgagePayload
+
+    # Some inline logging to demostrate inline steps
+    # This is also useful for debugging and tracing.
+    pl.step do |result|
+      p [:after_payload, result.value]
+      result
+    end
+
+    # Domain validation
+    pl.step ValidateMortgageAmount
+
+    # Save the application
+    pl.step MortgageApplicationsStore
+
+    # Notifications
+    pl.step NotifyCustomer
+  end
+
+  # Note that I could have also started the pipeline directly off the MortgagePayload type.
+  # ex. CreateMortageApplication2 = MortgagePayload.pipeline do |pl
+  # For super-tiny command objects you can do it all inline:
+  #
+  #   Types::Hash[
+  #     name: String,
+  #     age: Integer
+  #   ].pipeline do |pl|
+  #     pl.step do |result|
+  #       .. some validations
+  #       result
+  #     end
+  #   end
+  #
+  # Or you can use Method objects as steps
+  #
+  #   pl.step SomeObject.method(:create)
+
+  ###############################################################
+  # Option 3: use your own class
+  # Use Plumb internally for validation and composition of shared steps or method objects.
+  ###############################################################
+  class CreateMortgageApplication3
+    def initialize
+      @pipeline = Types::Any.pipeline do |pl|
+        pl.step MortgagePayload
+        pl.step method(:validate)
+        pl.step method(:save)
+        pl.step method(:notify)
+      end
+    end
+
+    def run(payload)
+      @pipeline.resolve(payload)
+    end
+
+    private
+
+    def validate(result)
+      # etc
+      result
+    end
+
+    def save(result)
+      # etc
+      result
+    end
+
+    def notify(result)
+      # etc
+      result
+    end
+  end
+end
+
+# Uncomment each case to run
+# p Types::CreateMortgageApplication1.resolve(
+#   customer: { name: 'John Doe', age: 30, email: 'john@doe.com' },
+#   property_value: 200_000,
+#   mortgage_amount: 150_000,
+#   term: 25
+# )
+
+# p Types::CreateMortgageApplication2.resolve(
+#   customer: { name: 'John Doe', age: 30, email: 'john@doe.com' },
+#   property_value: 200_000,
+#   mortgage_amount: 150_000,
+#   term: 25
+# )
+
+# Or, with invalid data
+# p Types::CreateMortgageApplication2.resolve(
+#   customer: { name: 'John Doe', age: 30, email: 'john@doe.com' },
+#   property_value: 200_000,
+#   mortgage_amount: 201_000,
+#   term: 25
+# )

data/examples/concurrent_downloads.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'bundler'
+Bundler.setup(:examples)
+require 'plumb'
+require 'open-uri'
+require 'fileutils'
+require 'digest/md5'
+
+# Mixin built-in Plumb types, and provide a namespace for core types and
+# pipelines in this example.
+module Types
+  include Plumb::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 (naive) step to download files from the internet
+  # and return an Image struct.
+  # It implements the #call(Result) => Result interface.
+  # required by all Plumb steps.
+  # URI => Image
+  Download = Plumb::Step.new do |result|
+    io = URI.open(result.value)
+    result.valid(Image.new(result.value.to_s, io))
+  end
+
+  # A configurable file-system cache to read and write files from.
+  class Cache
+    def initialize(dir = '.')
+      @dir = dir
+      FileUtils.mkdir_p(dir)
+    end
+
+    # 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.
+    def read = Plumb::Step.new(method(:reader))
+    def write = Plumb::Step.new(method(:writer))
+
+    private
+
+    # URL => Image
+    def reader(result)
+      path = path_for(result.value)
+      return result.invalid(errors: "file #{path} does not exist") unless File.exist?(path)
+
+      result.valid Types::Image.new(url: path, io: File.new(path))
+    end
+
+    # Image => Image
+    def writer(result)
+      image = result.value
+      path = path_for(image.url)
+      File.open(path, 'wb') { |f| f.write(image.io.read) }
+      result.valid image.with(url: path, io: File.new(path))
+    end
+
+    def path_for(url)
+      url = url.to_s
+      ext = File.extname(url)
+      name = [Digest::MD5.hexdigest(url), ext].compact.join
+      File.join(@dir, name)
+    end
+  end
+end
+
+###################################
+# Program 1: idempoent download of images from the internet
+# If not present in the cache, images are downloaded and written to the cache.
+# Otherwise images are listed directly from the cache (files on disk).
+###################################
+
+cache = Types::Cache.new('./examples/data/downloads')
+
+# A pipeline representing a single image download.
+# 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))
+
+# An array of downloadable images,
+# marked as concurrent so that all IO operations are run in threads.
+Images = Types::Array[IdempotentDownload].concurrent
+
+urls = [
+  'https://as1.ftcdn.net/v2/jpg/07/67/24/52/1000_F_767245234_NdiDr9LOkypOEKtXiDDoM1m42zBQ0hZe.jpg',
+  'https://as1.ftcdn.net/v2/jpg/07/83/02/00/1000_F_783020069_HaP9UCZs2UXUnKxpGHDoddt0vuX4vU9U.jpg',
+  'https://as2.ftcdn.net/v2/jpg/07/32/27/53/1000_F_732275398_r2t1cnxSXGUkZSgxtqhg40UupKiqcywJ.jpg',
+  'https://as1.ftcdn.net/v2/jpg/07/46/41/18/1000_F_746411866_WwQBojO7xMeVFTua2BuEZdKGDI2vsgAH.jpg',
+  'https://as2.ftcdn.net/v2/jpg/07/43/50/53/1000_F_743505311_MJ3zo09rH7rUvHrCKlBotojm6GLw3SCT.jpg',
+  'https://images.pexels.com/photos/346529/pexels-photo-346529.jpeg'
+]
+
+# raise CachedDownload.parse(url).inspect
+# raise CachedDownload.parse(urls.first).inspect
+# Run the program. The images are downloaded and written to the ./downloads directory.
+# Running this multiple times will only download the images once, and list them from the cache.
+# You can try deleting all or some of the files and re-running.
+Images.resolve(urls).tap do |result|
+  puts result.valid? ? 'valid!' : result.errors
+  result.value.each { |img| p img }
+end

data/examples/csv_stream.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'plumb'
+require 'csv'
+
+# Defines types and pipelines for opening and working with CSV streams.
+# Run with `bundle exec ruby examples/csv_stream.rb`
+module Types
+  include Plumb::Types
+
+  # Open a File
+  # ex. file = FileStep.parse('./files/data.csv') # => File
+  OpenFile = String
+             .check('no file for that path') { |s| ::File.exist?(s) }
+             .build(::File)
+
+  # Turn a File into a CSV stream
+  # ex. csv_enum = FileToCSV.parse(file) #=> Enumerator
+  FileToCSV = Types::Any[::File]
+              .build(CSV)
+              .transform(::Enumerator, &:each)
+
+  # Turn a string file path into a CSV stream
+  # ex. csv_enum = StrinToCSV.parse('./files/data.csv') #=> Enumerator
+  StringToCSV = OpenFile >> FileToCSV
+end
+
+#################################################
+# Program 1: stream a CSV list of programmers and filter them by age.
+#################################################
+
+# This is a CSV row for a programmer over the age of 18.
+AdultProgrammer = Types::Tuple[
+  # Name
+  String,
+  # Age. Coerce to Integer and constrain to 18 or older.
+  Types::Lax::Integer[18..],
+  # Programming language
+  String
+]
+
+# An Array of AdultProgrammer.
+AdultProgrammerArray = Types::Array[AdultProgrammer]
+
+# A pipeline to open a file, parse CSV and stream rows of AdultProgrammer.
+AdultProgrammerStream = Types::StringToCSV >> AdultProgrammerArray.stream
+
+# List adult programmers from file.
+puts 'Adult programmers:'
+AdultProgrammerStream.parse('./examples/programmers.csv').each do |row|
+  puts row.value.inspect if row.valid?
+end
+
+# The filtering can also be achieved with Stream#filter
+#  AdultProgrammerStream = Types::StringToCSV >> AdultProgrammerArray.stream.filtered
+
+#################################################
+# Program 2: list Ruby programmers from a CSV file.
+#################################################
+
+RubyProgrammer = Types::Tuple[
+  String, # Name
+  Types::Lax::Integer, # Age
+  Types::String[/^ruby$/i] # Programming language
+]
+
+# A pipeline to open a file, parse CSV and stream rows of AdultProgrammer.
+# This time we use Types::Stream directly.
+RubyProgrammerStream = Types::StringToCSV >> Types::Stream[RubyProgrammer].filtered
+
+# List Ruby programmers from file.
+puts
+puts '----------------------------------------'
+puts 'Ruby programmers:'
+RubyProgrammerStream.parse('./examples/programmers.csv').each do |person|
+  puts person.inspect
+end
+
+# We can filter Ruby OR Elixir programmers with a union type.
+# Lang = Types::String['ruby'] | Types::String['elixir']
+# Or with allowe values:
+# Lang = Types::String.options(%w[ruby elixir])
+
+#################################################
+# Program 3: negate the stream above to list non-Ruby programmers.
+#################################################
+
+# See the `.not` which negates the type.
+NonRubyProgrammerStream = Types::StringToCSV >> Types::Stream[RubyProgrammer.not].filtered
+
+puts
+puts '----------------------------------------'
+puts 'NON Ruby programmers:'
+NonRubyProgrammerStream.parse('./examples/programmers.csv').each do |person|
+  puts person.inspect
+end

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