hexx-entities 0.0.1

data/config/metrics/rubocop.yml

@@ -0,0 +1,72 @@
+---
+# settings added by the 'hexx-suit' module
+# output: "tmp/rubocop"
+# format: "html"
+
+AllCops:
+  Exclude:
+    - '**/db/schema.rb'
+
+Lint/HandleExceptions:
+  Exclude:
+    - '**/*_spec.rb'
+
+Lint/RescueException:
+  Exclude:
+    - '**/*_spec.rb'
+
+Style/AccessorMethodName:
+  Exclude:
+    - '**/*_spec.rb'
+
+Style/AsciiComments:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/EmptyLinesAroundBlockBody:
+  Enabled: false
+
+Style/EmptyLinesAroundClassBody:
+  Enabled: false
+
+Style/EmptyLinesAroundMethodBody:
+  Enabled: false
+
+Style/EmptyLinesAroundModuleBody:
+  Enabled: false
+
+Style/EmptyLineBetweenDefs:
+  Enabled: false
+
+Style/FileName:
+  Enabled: false
+
+Style/RaiseArgs:
+  EnforcedStyle: compact
+
+Style/SingleLineMethods:
+  Exclude:
+    - '**/*_spec.rb'
+
+Style/SingleSpaceBeforeFirstArg:
+  Enabled: false
+
+Style/SpecialGlobalVars:
+  Exclude:
+    - '**/Gemfile'
+    - '**/*.gemspec'
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/TrivialAccessors:
+  Exclude:
+    - '**/*_spec.rb'

data/config/metrics/saikuro.yml

@@ -0,0 +1,3 @@
+---
+warn_cyclo:  4
+error_cyclo: 6

data/config/metrics/simplecov.yml

@@ -0,0 +1,8 @@
+---
+output: tmp/coverage
+filters: # The list of paths to be excluded from coverage checkup
+- "spec/"
+- "config/"
+groups: # The list of groups to be shown in the coverage report
+  Libraries: "lib/"
+  Application: "app/"

data/config/metrics/yardstick.yml

@@ -0,0 +1,37 @@
+---
+# Settings added by the 'hexx-suit' gem
+output: "tmp/yardstick/output.log"
+path: "lib/**/*.rb"
+rules:
+  ApiTag::Presence:
+    enabled: true
+    exclude: []
+  ApiTag::Inclusion:
+    enabled: true
+    exclude: []
+  ApiTag::ProtectedMethod:
+    enabled: true
+    exclude: []
+  ApiTag::PrivateMethod:
+    enabled: false
+    exclude: []
+  ExampleTag:
+    enabled: true
+    exclude: []
+  ReturnTag:
+    enabled: true
+    exclude: []
+  Summary::Presence:
+    enabled: true
+    exclude: []
+  Summary::Length:
+    enabled: true
+    exclude: []
+  Summary::Delimiter:
+    enabled: true
+    exclude: []
+  Summary::SingleLine:
+    enabled: true
+    exclude: []
+threshold: 100
+verbose: false

data/hexx-entities.gemspec

@@ -0,0 +1,26 @@
+$:.push File.expand_path("../lib", __FILE__)
+require "hexx/entities/version"
+
+Gem::Specification.new do |gem|
+
+  gem.name        = "hexx-entities"
+  gem.version     = Hexx::Entities::VERSION.dup
+  gem.author      = "Andrew Kozin"
+  gem.email       = "andrew.kozin@gmail.com"
+  gem.homepage    = "https://github.com/nepalez/hexx-entities"
+  gem.summary     = "Base class for domain entities"
+  gem.license     = "MIT"
+
+  gem.files            = `git ls-files`.split($INPUT_RECORD_SEPARATOR)
+  gem.test_files       = Dir["spec/**/*.rb"]
+  gem.extra_rdoc_files = Dir["README.md", "LICENSE"]
+  gem.require_paths    = ["lib"]
+
+  gem.required_ruby_version = "~> 2.1"
+
+  gem.add_runtime_dependency "attestor", "~> 2.2"
+  gem.add_runtime_dependency "eigindir", "~> 0.0"
+
+  gem.add_development_dependency "hexx-rspec", "~> 0.4"
+
+end # Gem::Specification

data/lib/hexx/entities/base.rb

@@ -0,0 +1,76 @@
+# encoding: utf-8
+
+module Hexx::Entities
+
+  # Class Base provides a common interface for entities
+  #
+  # @example
+  #   require "hexx-entities"
+  #
+  #   class Item < Hexx::Entities::Base
+  #
+  #     # Defines attributes with their coercers
+  #     attribute :foo, coerce: ->(value) { value.to_s }
+  #
+  #     # Defines validation for the entity
+  #     validate { invalid :blank_foo unless foo }
+  #
+  #   end # class Item
+  #
+  # @author Andrew Kozin <Andrew.Kozin@gmail.com>
+  #
+  # @api public
+  class Base
+    include Attestor::Validations
+    include Comparable
+    include Eigindir
+
+    # @!scope class
+    # @!method new(attributes)
+    # Creates the entity and initializes its attributes
+    #
+    # @param [Hash] attributes
+    #
+    # @return [Hexx::Entities::Base]
+
+    # @private
+    def initialize(uuids: nil, **attributes)
+      @uuids = UUIDs.build Array(uuids)
+      self.attributes = attributes
+    end
+
+    # @!attribute [rw] uuids
+    #
+    # @return [Array<String>] The list of UUIDs that identify the entity
+    attribute_reader :uuids
+    validate { uuids.each(&:validate!) }
+
+    # Checks the equality of the entity to another object
+    #
+    # The entity is equal to any other entity that has at least one of its
+    # own uuids.
+    #
+    # @param [Object] other
+    #
+    # @return [Boolean]
+    def ==(other)
+      return false unless other.is_a? Base
+      (other.uuids & uuids).any?
+    end
+
+    # Recursively serializes the entity to the hash
+    #
+    # Returns the hash of entity attributes, where every attribute
+    # that responds to `serialize` is serialized in its turn.
+    #
+    # @return [Hash]
+    def serialize
+      values = attributes.values.map do |item|
+        item.respond_to?(:serialize) ? item.serialize : item
+      end
+      attributes.keys.zip(values).to_h
+    end
+
+  end # class Base
+
+end # module Hexx::Entities

data/lib/hexx/entities/uuid.rb

@@ -0,0 +1,41 @@
+# encoding: utf-8
+
+module Hexx::Entities
+
+  # Class UUID provides validatable value object that describes UUID
+  #
+  # @example Creates a string
+  #   uuid = UUID.new "12345678-90ab-cdef-1234-567890abcdef"
+  #   # => "12345678-90ab-cdef-1234-567890abcdef"
+  #
+  # @example Validates the format of its own
+  #   uuid = UUID.new "wrong format"
+  #   uuid.validate.valid? # => false
+  #
+  # @example Generates a default value for nil
+  #   uuid = UUID.new nil
+  #   # => "97f340af-8157-5c3a-1571-743d208da957"
+  #
+  # @see https://www.ietf.org/rfc/rfc4122.txt
+  #   the RFC 4220 standard for Universal Unique Identifiers (UUID)
+  #
+  # @author Andrew Kozin <Andrew.Kozin@gmail.com>
+  #
+  # @api public
+  class UUID < String
+    include Attestor::Validations
+
+    # @private
+    FORMAT = /^\h{8}(-\h{4}){3}-\h{12}$/
+
+    # @private
+    def initialize(value)
+      super (value || SecureRandom.uuid).to_s
+    end
+
+    # @private
+    validate { invalid :invalid unless self[FORMAT] }
+
+  end # class UUID
+
+end # module Hexx::Entities

data/lib/hexx/entities/uuids.rb

@@ -0,0 +1,34 @@
+# encoding: utf-8
+
+module Hexx::Entities
+
+  # Module UUIDs provides a builder utility to create a list of uuids
+  #
+  # @author Andrew Kozin <Andrew.Kozin@gmail.com>
+  #
+  module UUIDs
+
+    # Builds an immutable list of uuids from given list of values
+    #
+    # @example
+    #   value = "12345678-90ab-cdef-1234-567890abcdef"
+    #   list  = Hexx::Entities::UUIDs.build value
+    #
+    #   list == [value]  # => true
+    #   list.first.class # => Hexx::Entities::UUID
+    #   list.frozen?     # => true
+    #
+    # @example Generates default uuid if no uuids given
+    #   list = Hexx::Entities::UUIDs.build nil
+    #   list # => ["2bcfaedf-5f62-4929-861a-f8248f2bea16"]
+    #
+    # @param [Array<String>] values
+    #
+    # @return [Array<Hexx::Entities::UUID>] immutable (frozen) array of uuids
+    def self.build(values)
+      (values.empty? ? [nil] : values.uniq).map(&UUID.method(:new)).freeze
+    end
+
+  end # module UUIDs
+
+end # module Hexx::Entities

data/lib/hexx/entities/version.rb

@@ -0,0 +1,13 @@
+# encoding: utf-8
+
+module Hexx
+
+  module Entities
+
+    # The semantic version of the module.
+    # @see http://semver.org/ Semantic versioning 2.0
+    VERSION = "0.0.1".freeze
+
+  end # module Entities
+
+end # module Hexx

data/lib/hexx/entities.rb

@@ -0,0 +1,14 @@
+# encoding: utf-8
+
+module Hexx
+
+  # Module Entities provides a base class for domain entities
+  #
+  # @example (see Hexx::Entities::Base)
+  #
+  # @author Andrew Kozin <Andrew.Kozin@gmail.com>
+  module Entities
+
+  end # module Entities
+
+end # module Hexx

data/lib/hexx-entities.rb

@@ -0,0 +1,17 @@
+# encoding: utf-8
+
+require "attestor"      # for validations
+require "eigindir"      # for attributes
+require "securerandom"  # for uuids
+
+# Module Hexx provides the shared namespace for 'hexx' collection of gems
+#
+# @author Andrew Kozin <Andrew.Kozin@gmail.com>
+module Hexx
+
+  require_relative "hexx/entities" # for namespace
+  require_relative "hexx/entities/uuid"
+  require_relative "hexx/entities/uuids"
+  require_relative "hexx/entities/base"
+
+end # module Hexx

data/spec/spec_helper.rb

@@ -0,0 +1,12 @@
+# encoding: utf-8
+
+begin
+  require "hexx-suit"
+  Hexx::Suit.load_metrics_for(self)
+rescue LoadError
+  require "hexx-rspec"
+  Hexx::RSpec.load_metrics_for(self)
+end
+
+# Loads the code under test
+require "hexx-entities"

data/spec/tests/base_spec.rb

@@ -0,0 +1,132 @@
+# encoding: utf-8
+
+require "attestor/rspec"
+
+describe Hexx::Entities::Base do
+  include Attestor::RSpec # helpers and matchers for validations
+
+  let(:klass) { Class.new(described_class) }
+
+  subject(:entity) { klass.new }
+
+  describe ".new" do
+
+    it "creates validatable object" do
+      expect(subject).to be_kind_of Attestor::Validations
+    end
+
+    it "creates attributable object" do
+      expect(subject).to be_kind_of Eigindir
+    end
+
+    it "creates comparable object" do
+      expect(subject).to be_kind_of Comparable
+    end
+
+    it "initializes attributes from hash" do
+      klass.attribute :foo
+      subject = klass.new foo: :bar
+      expect(subject.foo).to eq :bar
+    end
+
+  end # describe .new
+
+  describe "#uuids" do
+
+    let(:uuid) { SecureRandom.uuid }
+
+    it "is an attribute" do
+      expect(subject.attributes.keys).to include :uuids
+    end
+
+    it "returns an array" do
+      expect(subject.uuids).to be_kind_of Array
+    end
+
+    it "has a default value" do
+      expect(subject.uuids.count).to eq 1
+      expect(subject.uuids.first).to be_kind_of Hexx::Entities::UUID
+    end
+
+    it "can be initialized" do
+      subject = klass.new(uuids: uuid)
+      expect(subject.uuids).to eq [uuid]
+      expect(subject.uuids.first).to be_kind_of Hexx::Entities::UUID
+    end
+
+    it "is immutable" do
+      expect(subject.uuids).to be_frozen
+    end
+
+  end # describe #uuids
+
+  describe "#==" do
+
+    let(:subclass) { Class.new(klass)  }
+    let(:uuid)     { SecureRandom.uuid }
+    let(:entity)   { klass.new uuids: [uuid, SecureRandom.uuid] }
+    subject        { entity == other }
+
+    context "to entity with the same uuid" do
+
+      let(:other) { subclass.new uuids: [SecureRandom.uuid, uuid] }
+      it { is_expected.to be true }
+
+    end # context
+
+    context "to entity with different uuids" do
+
+      let(:other) { subclass.new }
+      it { is_expected.to be false }
+
+    end # context
+
+    context "to non-entity" do
+
+      let(:other) { double }
+      it { is_expected.to be false }
+
+    end # context
+
+  end # describe #==
+
+  describe "#serialize" do
+
+    before { klass.attribute :foo }
+    before { klass.attribute :bar }
+
+    let(:bar)   { double }
+    let(:baz)   { double serialize: { baz: :baz } }
+    let(:uuids) { [SecureRandom.uuid] }
+
+    subject(:entity) { klass.new(uuids: uuids, foo: bar, bar: baz) }
+
+    it "returns a nested hash" do
+      expect(entity.serialize).to eq(uuids: uuids, foo: bar, bar: { baz: :baz })
+    end
+
+  end # describe #to_hash
+
+  describe "#validate" do
+
+    subject { entity.validate }
+
+    context "when every uuid is valid" do
+
+      let(:entity) { described_class.new }
+
+      it { is_expected.to be_valid }
+
+    end # context
+
+    context "when any uuid is invalid" do
+
+      let(:entity) { described_class.new uuids: [SecureRandom.uuid, "wrong"] }
+
+      it { is_expected.to be_invalid }
+
+    end # context
+
+  end # describe #validate
+
+end # describe Hexx::Entities::Base

data/spec/tests/uuid_spec.rb

@@ -0,0 +1,63 @@
+# encoding: utf-8
+
+require "attestor/rspec"
+
+describe Hexx::Entities::UUID do
+  include Attestor::RSpec
+
+  let(:value)    { SecureRandom.uuid.to_sym  }
+  subject(:uuid) { described_class.new value }
+
+  describe ".new" do
+
+    context "with something" do
+
+      it "creates a string" do
+        expect(subject).to eq value.to_s
+      end
+
+    end # context
+
+    context "with nil" do
+
+      let(:format)   { /^\h{8}(-\h{4}){3}-\h{12}$/ }
+      subject(:uuid) { described_class.new nil }
+
+      it "creates uuid by default" do
+        expect(subject).to match format
+      end
+
+    end # context
+
+    context "with nothing" do
+
+      subject(:uuid) { described_class.new }
+
+      it "fails" do
+        expect { subject }.to raise_error ArgumentError
+      end
+
+    end # context
+
+  end # describe .new
+
+  describe "#validate" do
+
+    subject { uuid.validate }
+
+    context "with valid uuid" do
+
+      it { is_expected.to be_valid }
+
+    end # context
+
+    context "with invalid value" do
+
+      let(:value) { "wrong" }
+      it { is_expected.to be_invalid }
+
+    end # context
+
+  end # describe #validate
+
+end # describe Hexx::Entities::UUID

data/spec/tests/uuids_spec.rb

@@ -0,0 +1,67 @@
+# encoding: utf-8
+
+describe Hexx::Entities::UUIDs do
+
+  describe ".build" do
+
+    subject { described_class.build values }
+
+    shared_examples "building immutable array of uuids" do
+
+      it "[returns an array]" do
+        expect(subject).to be_kind_of Array
+      end
+
+      it "[returns uuids]" do
+        subject.each { |item| expect(item).to be_kind_of Hexx::Entities::UUID }
+      end
+
+      it "[freezes the array]" do
+        expect(subject).to be_frozen
+      end
+
+    end # context
+
+    context "with non-empty uniq array" do
+
+      let(:values) { 2.times.map { SecureRandom.uuid } }
+
+      it_behaves_like "building immutable array of uuids"
+
+      it "uses given values" do
+        expect(subject).to match_array values
+      end
+
+    end # context
+
+    context "with non-empty non-uniq array" do
+
+      let(:values) { [SecureRandom.uuid] * 2 }
+
+      it_behaves_like "building immutable array of uuids"
+
+      it "removes duplications" do
+        expect(subject).to match_array values.uniq
+      end
+
+    end # context
+
+    context "with empty array" do
+
+      let(:values) { [] }
+
+      it_behaves_like "building immutable array of uuids"
+
+      it "creates one uuid" do
+        expect(subject.count).to eq 1
+      end
+
+      it "creates valid uuid" do
+        expect(subject.first.validate).to be_valid
+      end
+
+    end # context
+
+  end # describe .build
+
+end # describe Hexx::Entities::UUIDs