foobara 0.0.1

data/README.md

@@ -0,0 +1,50 @@
+# Foobara
+
+Foobara is a command-based software framework with an emphasis on reflection features to facilitate integration with
+other systems or subsystems. The focus of the framework is to provide these features to help
+with managing domain complexity in projects with higher domain complexity. However, Foobara
+is also expected to be pleasant for use in projects with simpler domains as well.
+
+## Installation
+
+To add foobara to an existing project, you can add `foobara` gem to your Gemfile or .gemspec as you normally would.
+
+To create a new project using a foobara generator, you could install the `foob` gem with `gem install foob` and then
+run `foob generate ruby-project --name your-org/your-new-project-name`
+
+## Usage
+
+TODO: Write usage instructions here or defer to some tutorial somewhere
+
+## Contributing
+
+Can contribute via a github pull request as is typical but see info about licensing below first.
+
+Make sure the test suite and linter pass locally before opening a pull request.
+The build will fail if test coverage is below 100%.
+
+It might be a good idea to reach out for advice if unsure how to chip away at the part of this project
+that you are interested in.
+
+### Developing locally
+
+You should be able to run `bundle install` and then `rake` to run the test suite and the linter.
+
+### Monorepo Structure
+
+Foobara is split up into many projects. Many are in separate repositories. This repository however is unique
+in the Foobara ecosystem of projects because it is a monorepo. Sometimes projects are extracted from here
+into their own repositories.
+
+Each project has its own directory in the projects/ directory.
+
+### Licensing
+
+Temporarily licensed under the AGPL-3.0 license. This is to to get the gem out there for convenient use in demos,
+releasing it under a very restrictive
+license to buy time on a final licensing decision (leaning towards `Apache-2.0 OR MIT`)
+
+My intention is to either release this under MIT license, Apache 2.0, or MPL,
+or a similar license (permissive or possibly weak copyleft.)
+
+See DECISION_LOG.md for the current thoughts on licensing.

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/concepts.md

@@ -0,0 +1,153 @@
+<!-- TOC -->
+
+* [Command](#command)
+* [Type < Value::Processor](#type--valueprocessor)
+* [type declaration value](#type-declaration-value)
+* [Type reference](#type-reference)
+* [Domain](#domain)
+* [Organization](#organization)
+* [Domain mapper](#domain-mapper)
+* [Value::Processor](#valueprocessor)
+    * [Value::Caster < Value::Processor](#valuecaster--valueprocessor)
+    * [Value::Validator < Value::Processor](#valuevalidator--valueprocessor)
+    * [Value::Transformer < Value::Processor](#valuetransformer--valueprocessor)
+    * [Desugarizer < Value::Transformer](#desugarizer--valuetransformer)
+    * [TypeDeclarationValidator < Value::Validator](#typedeclarationvalidator--valuevalidator)
+        * [in general:](#in-general)
+        * [types and type declarations:](#types-and-type-declarations)
+
+<!-- TOC -->
+
+These are notes about some things conceptual.
+
+# Command
+
+* A command is an encapsulation of a high-level business operation and is intended to be the public
+  interface of a system or subsystem.
+
+# Type < Value::Processor
+
+A type is an instance of the Types::Type class.
+
+It (the instance) is a namespace.
+
+It is a Value::Processor
+
+* reflection
+    * can give a type declaration value (formal or informal/sugary or strict) for this type
+    * can give the list of possible errors that could result from processing a value of this type
+      and the types for their context schemas
+    * can answer what value processors are supported for values of this type
+    * can answer which value processors are automatically applied for values of this type
+* can serve as a base type for another type
+* can process a value of this type
+    * can answer if a value needs to be cast
+    * can answer if a value can be cast
+    * can cast a value into an value of this type
+    * can transform a value of this type
+    * can validate a value of this type
+* processor registry operations
+    * can register a supported value processor
+    * can register a value caster
+
+# type declaration value
+
+* Something that defines/declares a type in a declarative fashion.
+    * Can have a sugary form for human expression/readability/writability
+    * Is easily serializable for cross-system metaprogramming
+* example:
+  ```ruby
+  { 
+    foo: :integer,
+    bar: [:integer, :optional, :allow_blank, min: 1]
+  }
+  ```
+* In this example, we are using a sugary declaration to specify a new type of
+  attributes type that can represent a value like `{ foo: -20, bar: 10 }`
+
+# Type reference
+
+* References a "registered" type. A registered type has a type symbol and belongs to a domain.
+* An unresolved type reference doesn't have to be absolute and is looked up in the current
+  Foobara namespace.
+* A resolved type is absolute.
+* A type reference can be used as a type declaration.
+
+# Domain
+
+* A namespace for Commands and Types
+* can depend on other domains in a unidirectional way
+
+# Organization
+
+* namespace for collecting domains
+
+# Domain mapper
+
+* Translates models (or types or commands inputs/results) to models (or types or command inputs/results) in
+  another domain.
+
+# Value::Processor
+
+* Has a process_value method that receives a value and returns an Outcome
+* Can have an applicable?(value) method
+* Answers what errors are possible
+    * Including the type of their context
+
+## Value::Caster < Value::Processor
+
+* gives #cast instead of #transform but same idea, takes value returns value
+* like ValueProcessor, never gives errors
+* only one value caster per type should be #applicable? for a given value.
+    * Therefore doesn't have to play nicely with other Casters, unlike Transformers/Validators
+
+## Value::Validator < Value::Processor
+
+* gives #validation_errors that takes value and returns errors
+* never gives new value
+
+## Value::Transformer < Value::Processor
+
+* gives #transfomer that takes value and returns value
+* never gives errors
+
+## Desugarizer < Value::Transformer
+
+* takes sugary type declaration and returns strict type declaration
+
+## TypeDeclarationValidator < Value::Validator
+
+* Validates type declarations
+
+A way to think about the interfaces/concepts involved here, if helpful:
+
+### in general:
+
+* Processor, Multi, Selection, Pipeline: value -> outcome
+* Multi < Processor: value -> outcome
+* Selection < Multi (chooses 1 processor among many to run): value -> outcome
+* Pipeline < Multi (chains a collection of processors together): value -> outcome
+* Processor, Multi, Selection, Pipeline: value -> outcome
+* Transformer: value -> value
+* Validator: value -> error[]
+
+Maybe not helpful, but, you could think of Processor/Multi/Selection/Pipeline as monads
+and Validator and Transformer as monads but with convenience methods that make assumptions
+about the context (transformer assumes there are no errors and validator assumes
+no transformation of the value.)
+
+### types and type declarations:
+
+* TypeDeclarationHandler: type declaration -> Type instance
+* TypeDeclarationHandlerRegistry: type declaration -> outcome<TypeDeclarationHandler>
+* Desugarizer: type declaration -> strict(er) type declaration
+* TypeDeclarationValidator: strict type declaration -> error[]
+* Type instance: value -> outcome
+* Type casting (is a Value::Pipeline of casters): value -> value
+* Caster: value -> value
+* Type transformers: value -> value
+* Type validators: value -> error[]
+* Type processors: value -> outcome
+* Supported type processors: value -> outcome
+* Supported type transformers: value -> value
+* Supported type validators: value -> error[]

data/projects/builtin_types/lib/foobara/builtin_types.rb

@@ -0,0 +1,67 @@
+require "date"
+require "time"
+require "bigdecimal"
+
+module Foobara
+  module BuiltinTypes
+    class << self
+      def builtin_types
+        @builtin_types ||= Set.new
+      end
+
+      def builtin?(type)
+        builtin_types.include?(type)
+      end
+
+      def [](symbol)
+        builtin_types.find do |type|
+          type.type_symbol == symbol
+        end
+      end
+
+      def install!
+        duck = build_and_register!(:duck, nil, ::Object)
+        # TODO: should we ban ::Object that are ::Enumerable from atomic_duck?
+        atomic_duck = build_and_register!(:atomic_duck, duck, ::Object)
+        build_and_register!(:symbol, atomic_duck)
+        # TODO: wtf why pass ::Object? It's to avoid casting? Do we need a way to flag abstract types?
+        number = build_and_register!(:number, atomic_duck, ::Object)
+        build_and_register!(:integer, number)
+        build_and_register!(:float, number)
+        build_and_register!(:big_decimal, number)
+        # Let's skip these for now since they rarely come up in business contexts and both could be
+        # represented by a tuple of numbers.
+        # build_and_register!(:rational, number)
+        # build_and_register!(:complex, number)
+        string = build_and_register!(:string, atomic_duck)
+        build_and_register!(:date, atomic_duck)
+        build_and_register!(:datetime, atomic_duck, ::Time)
+        build_and_register!(:boolean, atomic_duck, [::TrueClass, ::FalseClass])
+        build_and_register!(:email, string, ::String)
+        # TODO: not urgent and derisked already via :email
+        # phone_number = build_and_register!(:phone_number, string)
+        # TODO: wtf
+        duckture = build_and_register!(:duckture, duck, ::Object)
+        array = build_and_register!(:array, duckture)
+        build_and_register!(:tuple, array, ::Array)
+        associative_array = build_and_register!(:associative_array, duckture, ::Hash)
+        # TODO: uh oh... we do some translations in the casting here...
+        build_and_register!(:attributes, associative_array, nil)
+      end
+
+      def reset_all
+        builtin_types.each do |builtin_type|
+          builtin_type.foobara_each do |scoped|
+            if scoped.scoped_namespace == builtin_type
+              scoped.scoped_namespace = nil
+            end
+          end
+        end
+
+        builtin_types.clear
+
+        install!
+      end
+    end
+  end
+end

data/projects/builtin_types/src/README.md

@@ -0,0 +1,140 @@
+# Adding a new builtin type
+
+Note that adding a custom type is a different process involving writing handlers/desugarizers/declaration validators.
+TODO: add information to either this document or another about adding desugarizers, type declaration handlers,
+and type declaration validators.
+
+Let's go through the steps of adding a String builtin type
+
+## Create a directory for the new type
+
+```bash
+mkdir lib/foobara/builtin_types/string 
+```
+
+## Add Casters if needed
+
+```bash
+mkdir lib/foobara/builtin_types/string/casters
+```
+
+in `lib/foobara/builtin_types/string/casters/symbol.rb`
+
+```ruby
+
+module Foobara
+  module BuiltinTypes
+    module String
+      module Casters
+        class Symbol < Value::Caster
+          def applicable?(value)
+            value.is_a?(::Symbol)
+          end
+
+          def applies_message
+            "be a Symbol"
+          end
+
+          def cast(string)
+            string.to_s
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+## Creating SupportedProcessors/SupportedTransformers/SupportedValidators
+
+Let's make a validator for length
+
+```bash 
+mkdir lib/foobara/builtin_types/string/supported_validators
+```
+
+in `lib/foobara/builtin_types/string/supported_validators/max_length.rb`
+
+```ruby
+
+module Foobara
+  module BuiltinTypes
+    module String
+      module SupportedValidators
+        class MaxLength < TypeDeclarations::Validator
+          class MaxLengthExceededError < Foobara::Value::DataError
+            class << self
+              def context_type_declaration
+                {
+                  value: :string,
+                  max_length: :integer
+                }
+              end
+            end
+          end
+
+          def validation_errors(string)
+            if string.length > max_length
+              build_error(string)
+            end
+          end
+
+          def error_message(_value)
+            "Max length exceeded. Cannot be longer than #{max_length} characters"
+          end
+
+          def error_context(value)
+            {
+              value:,
+              max_length:
+            }
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+## Let's create a supported transformer
+
+in `lib/foobara/builtin_types/string/supported_transformers/downcase.rb`
+
+```ruby
+
+module Foobara
+  module BuiltinTypes
+    module String
+      module SupportedTransformers
+        class Downcase < Value::Transformer
+          def transform(string)
+            string.downcase
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+## Assemble our new type on boot by adding it to builtin_types.rb
+
+in `build_and_register_all_builtins_and_install_type_declaration_extensions!` in `lib/foobara/builtin_types.rb`
+
+```ruby
+string = build_and_register!(:string, atomic_duck)
+```
+
+## Trying it out...
+
+You could test this in a console with:
+
+```ruby
+$ bin / console
+irb(main) : 001 : 0 > type = Foobara::TypeDeclarations::TypeBuilder.type_for_declaration(:string, :downcase, max_length: 10)
+=> #<Foobara::Types::Type:0x00007fb12f5ca160 ...>
+  irb(main) : 002 : 0 > type.process_value!("Foo Bar")
+=> "foo bar"
+irb(main) : 003 : 0 > type.process_value("Foo Bar Baz").errors.first.message
+=> "Max length exceeded. Cannot be longer than 10"
+```

data/projects/builtin_types/src/array/casters/arrayable.rb

@@ -0,0 +1,22 @@
+module Foobara
+  module BuiltinTypes
+    module Array
+      module Casters
+        class Arrayable < Value::Caster
+          def applicable?(value)
+            !value.is_a?(::Array) && value.respond_to?(:to_a)
+          end
+
+          def applies_message
+            "respond to :to_a"
+          end
+
+          def cast(object)
+            # TODO: This is probably too lenient
+            object.to_a
+          end
+        end
+      end
+    end
+  end
+end

data/projects/builtin_types/src/array/supported_processors/element_type_declaration.rb

@@ -0,0 +1,41 @@
+module Foobara
+  module BuiltinTypes
+    module Array
+      module SupportedProcessors
+        class ElementTypeDeclaration < TypeDeclarations::ElementProcessor
+          def element_type
+            @element_type ||= type_for_declaration(element_type_declaration)
+          end
+
+          def process_value(array)
+            errors = []
+
+            array.each.with_index do |element, index|
+              element_outcome = element_type.process_value(element)
+
+              if element_outcome.success?
+                array[index] = element_outcome.result
+              else
+                element_outcome.each_error do |error|
+                  error.prepend_path!(index)
+
+                  errors << error
+                end
+              end
+            end
+
+            Outcome.new(result: array, errors:)
+          end
+
+          def possible_errors
+            super + element_type.possible_errors.map do |possible_error|
+                      possible_error = possible_error.dup
+                      possible_error.prepend_path!(:"#")
+                      possible_error
+                    end
+          end
+        end
+      end
+    end
+  end
+end

data/projects/builtin_types/src/array/supported_validators/size.rb

@@ -0,0 +1,43 @@
+module Foobara
+  module BuiltinTypes
+    module Array
+      module SupportedValidators
+        class Size < TypeDeclarations::Validator
+          class IncorrectTupleSizeError < Value::DataError
+            class << self
+              def context_type_declaration
+                {
+                  expected_size: :integer,
+                  actual_size: :integer,
+                  value: :array
+                }
+              end
+            end
+          end
+
+          def expected_size
+            size
+          end
+
+          def validation_errors(array)
+            if array.size != expected_size
+              build_error(array)
+            end
+          end
+
+          def error_message(array)
+            "Invalid tuple size. #{array.inspect} should have had #{expected_size} elements but had #{array.size}."
+          end
+
+          def error_context(array)
+            {
+              expected_size:,
+              actual_size: array.size,
+              value: array
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/projects/builtin_types/src/associative_array/casters/array.rb

@@ -0,0 +1,22 @@
+module Foobara
+  module BuiltinTypes
+    # TODO: rename to Map to avoid thinking of it as an array of pairs which isn't quite the right mental model.
+    module AssociativeArray
+      module Casters
+        class Array < Value::Caster
+          def applicable?(value)
+            value.is_a?(::Array) && value.all? { |element| element.is_a?(::Array) && element.size == 2 }
+          end
+
+          def applies_message
+            "be a an array of pairs"
+          end
+
+          def cast(array)
+            array.to_h
+          end
+        end
+      end
+    end
+  end
+end

data/projects/builtin_types/src/associative_array/supported_processors/key_type_declaration.rb

@@ -0,0 +1,44 @@
+module Foobara
+  module BuiltinTypes
+    module AssociativeArray
+      module SupportedProcessors
+        class KeyTypeDeclaration < TypeDeclarations::ElementProcessor
+          def key_type
+            @key_type ||= type_for_declaration(key_type_declaration)
+          end
+
+          def process_value(attributes_hash)
+            errors = []
+
+            attributes_hash = attributes_hash.to_a.map.with_index do |(key, value), index|
+              key_outcome = key_type.process_value(key)
+
+              if key_outcome.success?
+                key = key_outcome.result
+              else
+                key_outcome.each_error do |error|
+                  # Can' prepend path since we dont know if key is a symbolizable type...
+                  error.prepend_path!(index, :key)
+
+                  errors << error
+                end
+              end
+
+              [key, value]
+            end.to_h
+
+            Outcome.new(result: attributes_hash, errors:)
+          end
+
+          def possible_errors
+            super + key_type.possible_errors.map do |possible_error|
+                      possible_error = possible_error.dup
+                      possible_error.prepend_path!(:"#", :key)
+                      possible_error
+                    end
+          end
+        end
+      end
+    end
+  end
+end

data/projects/builtin_types/src/associative_array/supported_processors/value_type_declaration.rb

@@ -0,0 +1,44 @@
+module Foobara
+  module BuiltinTypes
+    module AssociativeArray
+      module SupportedProcessors
+        class ValueTypeDeclaration < TypeDeclarations::ElementProcessor
+          def value_type
+            @value_type ||= type_for_declaration(value_type_declaration)
+          end
+
+          def process_value(attributes_hash)
+            errors = []
+
+            attributes_hash = attributes_hash.to_a.map.with_index do |(key, value), index|
+              value_outcome = value_type.process_value(value)
+
+              if value_outcome.success?
+                value = value_outcome.result
+              else
+                value_outcome.each_error do |error|
+                  # Can' prepend path since we dont know if key is a symbolizable type...
+                  error.prepend_path!(index, :value)
+
+                  errors << error
+                end
+              end
+
+              [key, value]
+            end.to_h
+
+            Outcome.new(result: attributes_hash, errors:)
+          end
+
+          def possible_errors
+            super + value_type.possible_errors.map do |possible_error|
+                      possible_error = possible_error.dup
+                      possible_error.prepend_path!(:"#", :value)
+                      possible_error
+                    end
+          end
+        end
+      end
+    end
+  end
+end

data/projects/builtin_types/src/atomic_duck.rb

@@ -0,0 +1,6 @@
+module Foobara
+  module BuiltinTypes
+    module AtomicDuck
+    end
+  end
+end

data/projects/builtin_types/src/attributes/casters/array.rb

@@ -0,0 +1,33 @@
+module Foobara
+  module BuiltinTypes
+    module Attributes
+      module Casters
+        class Array < AssociativeArray::Casters::Array
+          def applicable?(value)
+            if super
+              hash_caster.applicable?(to_h(value))
+            end
+          end
+
+          def applies_message
+            "be a an array of pairs"
+          end
+
+          def cast(array)
+            hash_caster.cast(super)
+          end
+
+          private
+
+          def hash_caster
+            @hash_caster ||= Hash.instance
+          end
+
+          def to_h(value)
+            method(:cast).super_method.call(value)
+          end
+        end
+      end
+    end
+  end
+end