tomyum 0.1.0.a

data/lib/tomyum/assertions.rb

@@ -0,0 +1,80 @@
+module Tomyum
+  # Declarative way to deal with errors
+  module Assertions
+    Error       = Class.new(StandardError)
+    KeyError    = Class.new(Error)
+    SubsetError = Class.new(Error)
+
+    extend self
+    def self.included(object)
+      object.extend(self)
+    end
+
+    # Usage
+    #
+    # Use default error message
+    #
+    #   assert valid?
+    #
+    # Use custom error message
+    #
+    #   assert valid?, "Invalid value"
+    #
+    # Use custom Error class
+    #
+    #   assert valid?, ValidationError, "Invalid value"
+    def assert(object, *msgs)
+      raises Error, msgs << "#{object.class} is not a truthy" unless object
+    end
+
+    def assert_not(object, *msgs)
+      raises Error, msgs << "#{object.class} is not a falsey" if object
+    end
+
+    def assert_kind_of(classes, object, *msgs)
+      classes = normalize_array(classes)
+      found   = classes.find { |klass| object.kind_of?(klass) }
+
+      raises Error, msgs << "#{object.class} must be an instance of #{classes.map(&:name).join(', ')}" unless found
+    end
+
+    alias_method :assert_kind_of_either, :assert_kind_of
+
+    # Usage
+    #
+    #   assert_in ["john", "joe"], "joe"
+    #   assert_in { amount: 1 }, :amount
+    def assert_in(list, value, *msgs)
+      raises KeyError, msgs << "#{value.class} - #{value} is not in the #{list.keys}" if list.respond_to?(:key?) && !list.key?(value)
+      raises KeyError, msgs << "#{value.class} - #{value} is not in the #{list}" if list.kind_of?(Array) && !list.include?(value)
+    end
+
+    def assert_subset_of(parent, subset, *msgs)
+      rest = subset - parent
+      raises SubsetError, msgs << "#{rest} are not subset of #{parent}" if rest.present?
+    end
+
+    private
+
+    def normalize_array(values)
+      values.respond_to?(:each) ? values : [values]
+    end
+
+    # allow caller to pass custom Error
+    def raises(error, msgs = [])
+      error, msg = msgs unless msgs.first.kind_of?(String)
+
+      # Error class has its own error message and caller
+      # doesn't specify custom message
+      if msgs.length == 2
+        if error.respond_to?(:message)
+          msg = error.message
+        elsif error.respond_to?(:new)
+          msg = error.new&.message
+        end
+      end
+
+      raise error, msg || msgs.last
+    end
+  end
+end

data/lib/tomyum/attributes/array.rb

@@ -0,0 +1,11 @@
+require_relative "attribute"
+
+module Tomyum
+  module Attributes
+    class Array < Attribute
+      def native_type
+        "array"
+      end
+    end
+  end
+end

data/lib/tomyum/attributes/attribute.rb

@@ -0,0 +1,130 @@
+module Tomyum
+  module Attributes
+    # An abstract Attribute based class.
+    #
+    # @abstract
+    class Attribute
+      include Tomyum::Assertions
+      include Tomyum::Serializers::Serializable
+      include Tomyum::Validators::Normalizable
+      include Tomyum::Validators::Validatable
+
+      class_attribute :options
+      attr_reader     :name
+
+      # Assigns default class attribute values
+      self.options    = {}.freeze
+
+      def initialize(name, options = {})
+        @name    = name
+        @options = self.class.options.merge(options)
+      end
+
+      def options
+        @options.merge({
+          name:         @name,
+          match:        match,
+          method:       method,
+          type:         type,
+          native_type:  native_type,
+          of:           of,
+          in:           send(:in),
+          if:           @options[:if],
+          unless:       @options[:unless],
+          null:         null,
+          spec:         spec,
+          spec_uri:     spec_uri,
+          format:       format,
+          private:      private,
+          deprecated:   deprecated,
+          required:     required,
+          default:      default,
+          description:  description,
+          attributes:   attributes.values&.map(&:options),
+        })
+      end
+
+      def type
+        self.class.name.demodulize.chomp("Attribute").underscore
+      end
+
+      def match
+        @options[:match]
+      end
+
+      def method
+        @options[:method] || @name
+      end
+
+      def of
+        @options[:of]
+      end
+
+      def in
+        @options[:in]
+      end
+
+      def if
+        @options[:if]
+      end
+
+      def unless
+        @options[:unless]
+      end
+
+      def null
+        @options.fetch(:null, false)
+      end
+
+      def native_type
+        type
+      end
+
+      def format
+        @options[:format]
+      end
+
+      def spec
+        nil
+      end
+
+      def spec_uri
+        nil
+      end
+
+      def attributes
+        {}
+      end
+
+      # deprecated attribute should be listed in schema
+      def deprecated
+        @options.fetch(:deprecated, false)
+      end
+
+      def private
+        @options.fetch(:private, false)
+      end
+
+      def required
+        @options.fetch(:required, false)
+      end
+
+      def default
+        @options[:default]
+      end
+
+      def description
+        @options[:description]
+      end
+
+      # Should not be listed in schema or serialize this attribute
+      def serializable?
+        !private
+      end
+
+      def value(value)
+        value.nil? ? default : value
+      end
+    end
+  end
+end

data/lib/tomyum/attributes/boolean.rb

@@ -0,0 +1,22 @@
+require_relative "attribute"
+
+module Tomyum
+  module Attributes
+    # @example Registers custom normalizer that accepts "on" as truth value
+    #   Boolean.normalizer = ->(x) { ["on", true].include?(x) ? true : false }
+    #
+    # @example Registers custom serializer
+    #   Boolean.serialize = ->(x) { x == "on" ? true : false }
+    class Boolean < Attribute
+      self.serializer = ->(v) { ActiveModel::Type::Boolean.new.cast(v) }
+
+      def native_type
+        "boolean"
+      end
+
+      def in
+        @options.fetch(:in, [true, false])
+      end
+    end
+  end
+end

data/lib/tomyum/attributes/currency.rb

@@ -0,0 +1,19 @@
+require_relative "attribute"
+
+module Tomyum
+  module Attributes
+    class Currency < String
+      def format
+        super || type
+      end
+
+      def spec
+        "ISO 4217"
+      end
+
+      def spec_uri
+        "https://en.wikipedia.org/wiki/ISO_4217"
+      end
+    end
+  end
+end

data/lib/tomyum/attributes/date.rb

@@ -0,0 +1,11 @@
+require_relative "attribute"
+
+module Tomyum
+  module Attributes
+    class Date < String
+      def format
+        super || "date"
+      end
+    end
+  end
+end

data/lib/tomyum/attributes/float.rb

@@ -0,0 +1,13 @@
+require_relative "attribute"
+
+module Tomyum
+  module Attributes
+    class Float < Number
+      self.serializer = ->(v) { v.to_f }
+
+      def format
+        super || "float"
+      end
+    end
+  end
+end

data/lib/tomyum/attributes/integer.rb

@@ -0,0 +1,14 @@
+require_relative "attribute"
+
+module Tomyum
+  module Attributes
+    class Integer < Number
+      self.serializer = ->(v) { v.to_i }
+
+      # JSON schema supports `integer` type
+      def native_type
+        "integer"
+      end
+    end
+  end
+end

data/lib/tomyum/attributes/ip_address.rb

@@ -0,0 +1,15 @@
+require_relative "attribute"
+
+module Tomyum
+  module Attributes
+    class IPAddress < String
+      def spec
+        "RFC 2673 § 3.2"
+      end
+
+      def spec_uri
+        "https://tools.ietf.org/html/rfc2673#section-3.2"
+      end
+    end
+  end
+end

data/lib/tomyum/attributes/number.rb

@@ -0,0 +1,24 @@
+require_relative "attribute"
+
+module Tomyum
+  module Attributes
+    class Number < Attribute
+      self.serializer = ->(v) { v.to_s.include?(".") ? v.to_f : v.to_i }
+
+      RULES = {
+        max: {
+          group: :numericality,
+          name:  :less_than_or_equal,
+        },
+        min: {
+          group: :numericality,
+          name:  :greater_than_or_equal,
+        },
+      }.freeze
+
+      def native_type
+        "number"
+      end
+    end
+  end
+end

data/lib/tomyum/attributes/object.rb

@@ -0,0 +1,71 @@
+require_relative "attribute"
+
+module Tomyum
+  module Attributes
+    class Object < Attribute
+      class_attribute :stacks
+      attr_reader     :attributes
+
+      self.stacks = []
+
+      def initialize(name, options = {}, &block)
+        super
+
+        @attributes = {}
+        instance_exec(&block) if block_given?
+      end
+
+      def native_type
+        "object"
+      end
+
+      # Apply default options to all attributes
+      #
+      # group if: :deleted? { ... }
+      # group unless: :deleted? { ... }
+      # group if: ->{ @user.deleted? } { ... }
+      def group(options, &block)
+        return unless block_given?
+
+        # Use stacks to allow nested conditions
+        self.class.stacks << Attribute.options
+        Attribute.options = options
+
+        instance_exec(&block)
+
+        # restore options
+        Attribute.options = self.class.stacks.pop
+      end
+
+      # Shortcut for creating attribute (delegate call to Registry.create)
+      # This allows us to access newly registered attributes
+      #
+      #   string :username (or array, number etc)
+      def method_missing(type, name = nil, options = {}, &block)
+        if Attributes.registry.key?(type)
+          @attributes[name] = Attributes.create(type, name, options, &block)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method, *)
+        super
+      end
+
+      def [](name)
+        @attributes[name.to_sym]
+      end
+
+      def []=(name, attribute)
+        assert_kind_of Attribute, attribute
+
+        @attributes[name.to_sym] = attribute
+      end
+
+      def keys
+        @attributes.keys
+      end
+    end
+  end
+end

data/lib/tomyum/attributes/schema.rb

@@ -0,0 +1,23 @@
+require_relative "attribute"
+
+module Tomyum
+  module Attributes
+    # Reference to other schema and doesn't accept &block.
+    #
+    # Schema supports extra option named `expandable`
+    # which will either return `id` or `serialized object`
+    # as the result.
+    class Schema < Object
+      DEFAULT_EXPANDABLE = false
+      def initialize(name, options = {})
+        # automatically add name to :of if it's not given
+        options[:of] = name unless options.key?(:of)
+        @expandable  = options.fetch(:expandable, DEFAULT_EXPANDABLE)
+
+        super
+      end
+
+      attr_reader :expandable
+    end
+  end
+end

data/lib/tomyum/attributes/string.rb

@@ -0,0 +1,36 @@
+require_relative "attribute"
+
+module Tomyum
+  module Attributes
+    class String < Attribute
+      self.serializer = ->(v) { v.to_s }
+
+      RULES = {
+        match: {
+          group: :format,
+          name:  :with,
+        },
+        min: {
+          group: :length,
+          name:  :minimum,
+        },
+        max: {
+          group: :length,
+          name:  :maximum,
+        },
+        range: {
+          group: :length,
+          name:  :in,
+        },
+      }.freeze
+
+      def native_type
+        "string"
+      end
+
+      def in
+        super&.map(&:to_s)
+      end
+    end
+  end
+end

data/lib/tomyum/attributes/time.rb

@@ -0,0 +1,19 @@
+require_relative "attribute"
+
+module Tomyum
+  module Attributes
+    class Time < String
+      def format
+        super || "date-time"
+      end
+
+      def spec
+        "ISO 8601"
+      end
+
+      def spec_uri
+        "https://en.wikipedia.org/wiki/ISO_8601"
+      end
+    end
+  end
+end

data/lib/tomyum/attributes/uri.rb

@@ -0,0 +1,19 @@
+require_relative "attribute"
+
+module Tomyum
+  module Attributes
+    class URI < String
+      def format
+        super || type
+      end
+
+      def spec
+        "RFC 3986"
+      end
+
+      def spec_uri
+        "https://tools.ietf.org/html/rfc3986"
+      end
+    end
+  end
+end

data/lib/tomyum/attributes/visitor.rb

@@ -0,0 +1,136 @@
+module Tomyum
+  module Attributes
+    # An abstract Visitor for traversing {Attribute}.
+    #
+    # Sub-classes must implement the methods correspond to {Attribute} classes.
+    #
+    # @example Implements +string+ visitor for {String}
+    #   class SimpleVisitor < Tomyum::Attributes::Visitor
+    #     def visit_string(attribute, *args)
+    #       "Hello #{attribute.name}"
+    #     end
+    #   end
+    #
+    #   # Usage
+    #   username = Attributes.create(:string, :username)
+    #   visitor  = StringVisitor.new
+    #   visitor.visit(username) # => "Hello username"
+    #
+    # @abstract
+    class Visitor
+      include Functions
+
+      MethodNotFound = Tomyum::Error.create("Cannot find method Visitor#%s")
+
+      # Traveres a visitable object and calls corresponding method based-on
+      # sub-classes' impementations.
+      #
+      # @example When +attribute+ is an instance of {Attribute}.
+      #   object = Attributes.create(:object, :user) { }
+      #   visit(object) # => visit_object
+      #
+      # @example When +attribute+ is a {Symbol}.
+      #   visit(:user) # => visit_user or visit_schema(attr, of: :user)
+      #
+      # @param [Attribute|Symbol] The +Attribute+ object or +Symbol+
+      def visit(attribute, *args)
+        method, attribute = find_method!(attribute, *args)
+
+        send(method, attribute, *args)
+      end
+
+      # Performs visitor logic when no corresponding method can be found (Catch-all).
+      def visit_attribute(attribute, options = {})
+        raise NotImplementedError
+      end
+
+      def visit_schema(attribute, options = {})
+        raise NotImplementedError
+      end
+
+      private
+
+      # Finds a vistor method.
+      #
+      # @return Array<String, Attribute> Pair of method name and +Attribute+ object
+      #
+      # It'll return a first callable method in the chains or return +nil+ when no methods can be found.
+      # If +attribute+ is a Symbol. It'll stop looking any further.
+      #
+      #   find_method(:integer) # => `visit_integer`
+      #
+      # If it's an instance of <tt>Attribute</tt>. It'll look up in ancestors
+      # chain and return the first callable method.
+      #
+      #   object = Attributes.create(:object, :name) { ... }
+      #   find_method(object) => `visit_object`
+      def find_method(attribute, *args)
+        compose(
+          curry(:resolve_methods),
+          curry(:respond_to_visitor?),
+          curry(:normalize_symbol, attribute, args)
+        ).(attribute)
+      end
+
+      def find_method!(attribute, *args)
+        method, attribute = find_method(attribute, *args)
+
+        raise MethodNotFound, normalize_method(attribute) unless method
+
+        [method, attribute]
+      end
+
+      # Returns list of method Symbols from given +Attribute+
+      #
+      # @return [Symbol] Method symbols e.g. [:string, String, Attribute]
+      def resolve_methods(attribute)
+        return [attribute] if attribute.kind_of?(Symbol)
+
+        # Finds all ancestors in hierarchy up to `Attribute`
+        parents = attribute.class.ancestors.map(&:to_s)
+        parents.slice(0, parents.index(Attribute.name).to_i + 1)
+      end
+
+      def normalize_method(method)
+        return unless method
+
+        # Cannot use `chomp("Attribute")` here, because the top most class is `Attribute`
+        "visit_" + method.to_s.demodulize.gsub(/(\w+)Attribute/, "\\1").underscore
+      end
+
+      # Creates Attribute from symbol
+      # e.g. :integer to Integer
+      def normalize_attribute(attribute, options = {})
+        return attribute unless Attributes.key?(attribute)
+
+        Attributes.create(attribute, attribute.to_s, options)
+      end
+
+      # Finds method from method list that respond_to `visit_{attribute}` call
+      def respond_to_visitor?(methods)
+        methods.find { |m| respond_to?(normalize_method(m)) }
+      end
+
+      def normalize_symbol(attribute, args, method)
+        # When we can't find method e.g. `visit_{method}`
+        # and `attribute` is a symbol (e.g. :user),
+        # we'll enforce the same logic for all visitor sub-classes
+        # by calling `visit_schema` with of: attribute
+        if !method && attribute.kind_of?(Symbol)
+          method, attribute = normalize_schema_symbol(attribute, *args)
+        end
+
+        [
+          normalize_method(method),
+          normalize_attribute(attribute, *args),
+        ]
+      end
+
+      def normalize_schema_symbol(schema, *args)
+        args.last[:of] = schema if args.last.is_a?(Hash)
+
+        [:schema, :schema]
+      end
+    end
+  end
+end